워크플로 만들기

워크플로 만들기 (Build a workflow)

워크플로(Workflow)는 크래시·재시도·긴 대기까지 견디는 다단계 AI 파이프라인을 만들 수 있게 해줘요. 코드는 내 환경에서 실행되고, Mistral이 오케스트레이션·상태 관리·관측성(observability)을 책임져요. 이 퀵스타트를 끝내면 로컬에서 실행되는 워크플로를 하나 갖게 되고, Mistral 콘솔에서 그 워크플로를 트리거할 수 있어요. 완료까지 약 15분 걸려요.

출처: 문서

본문

필수 조건 (Prerequisites)

  • Mistral API 키 (아직 없으면 "첫 API 요청 보내기" 가이드를 참고해요)
  • Python 3.12 이상
  • uv 설치됨 (uvx가 함께 딸려 옴)

Step 1: 프로젝트 뼈대 만들기

터미널에서 다음 명령을 실행해요.

uvx mistralai-workflows-cli setup

이 CLI가 바로 실행 가능한 Python 프로젝트를 생성하면서 Mistral API 키를 물어봐요. 요청이 오면 키를 입력하세요 — 키는 프로젝트의 환경 설정에 저장돼요. 생성된 디렉터리(기본 이름 my-workflow)를 편집기에서 열면 돼요.

Step 2: 워크플로 이해하기

src/workflows/hello.py를 열어보면 뼈대 프로젝트에 간단한 예시가 들어 있어요.

from pydantic import BaseModel
import mistralai.workflows as workflows

class HelloInput(BaseModel):
    name: str = "World"

@workflows.activity()
async def greet(name: str) -> str:
    return f"Hello, {name}! Welcome to Mistral Workflows."

@workflows.workflow.define(
    name="hello-world",
    workflow_display_name="Hello World",
    workflow_description="A minimal hello-world workflow.",
)
class HelloWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, input: HelloInput) -> str:
        return await greet(input.name)

두 가지만 눈여겨보면 돼요.

  • @workflows.activity()는 함수를 지속성 있는(durable) 단계로 표시해요. 실행 도중 프로세스가 죽어도 플랫폼이 마지막으로 완료된 activity부터 다시 재생(replay)해요.
  • @workflows.workflow.define은 워크플로를 트리거할 때 쓸 이름으로 등록해요.

Step 3: 워커 시작하기

프로젝트 루트에서 다음을 실행해요.

make start-worker

워커가 Mistral API에 연결되어 워크플로를 등록하고 태스크를 기다려요. 이 터미널은 열어둔 채로 두세요.

Step 4: 워크플로 트리거하기

워커가 실행 중인 상태에서 두 번째 터미널을 열고 Makefile 명령으로 실행을 트리거해요.

make execute workflow=hello-world input='{"name": "World"}'

Mistral 콘솔에서도 트리거할 수 있어요.

  • 사이드바에서 Workflows로 이동
  • hello-world 선택
  • Start Workflow 클릭 후 {"name": "World"}를 input으로 전달
  • Executions 탭에서 실행을 지켜보기

검증 (Verify)

실행이 완료되면 다음과 같은 결과가 나와요.

{
  "result": "Hello, World! Welcome to Mistral Workflows."
}

워커 터미널에 연결 에러가 보이면 API 키가 올바르게 설정됐는지, 워커 프로세스가 아직 실행 중인지 확인하세요. 작업이 끝나면 Ctrl+C로 워커를 멈추면 돼요.

더 알아보기 (Learn more)