Studio API를 사용하면 애플리케이션에서 문서 처리 워크플로우를 만들고 실행할 수 있어요. 문서를 처리하는 순서를 한 번 저장하고, 새 문서가 들어올 때마다 같은 작업을 반복할 수 있습니다.
워크플로우는 반복해서 사용할 문서 처리 절차예요. Document Parse나 Information Extract API가 각각 한 가지 기능을 호출한다면, 워크플로우는 여러 처리 단계와 설정을 묶어 저장하고 실행합니다. 이 가이드에서는 Studio 화면에서 미리 만들지 않고 API로 처음부터 시작해요.
이미 Studio에서 만든 워크플로우가 있나요? 기존 워크플로우로 실행하기로 이동하세요.
이 예제에서 만들 것
샘플 청구서에서 청구서 번호와 총액을 추출해 볼게요. Parse(인식)가 문서 내용을 읽고, Extract(추출)가 지정한 항목을 골라냅니다.
청구서 PDF → 내용 인식 → 번호·총액 추출 → JSON 데이터
아래 가상 샘플에서 확인할 결과 형태예요. 실제 API 응답을 기록한 것이 아닌 설명용 예시입니다.
1. 워크플로우 만들기
Python은 OpenAI SDK, cURL은 Bash와 jq를 사용해요. UPSTAGE_API_KEY에 API 키를 설정하고, 같은 언어의 예제를 순서대로 실행하세요.
먼저 이름을 붙여 워크플로우를 만들어요. 실제로 어떤 순서로 처리할지는 다음 단계에서 저장합니다.
응답 일부예요. 문서의 ID는 예시이며 실제로는 반환된 값을 사용합니다.
코드는 id를 workflow_id에 저장해요. 이후 같은 워크플로우를 사용할 때 필요한 값입니다. API 경로의 /agents와 agt_로 시작하는 ID는 기존 이름을 유지하며, 이 가이드에서는 워크플로우를 가리켜요.
2. 처리 단계와 추출 항목 저장하기
설정 버전(Config)은 처리 단계와 각 단계의 옵션을 함께 저장한 것이에요. 처리 단계는 문서 인식이나 정보 추출처럼 한 가지 작업을 뜻하며, Studio 화면에서는 노드라고 불러요. 아래 steps는 Parse 다음에 Extract가 실행되도록 연결합니다.
json_schema의 스키마는 추출할 항목과 값의 형식을 정한 설정이에요. invoice_number는 문자열(string), total은 숫자(number)로 받습니다. 자신의 문서에서 다른 항목을 추출하려면 이 부분을 바꾸면 돼요.
응답 일부:
is_first는 시작 단계, next_steps는 다음 단계의 이름을 정해요. 마지막 단계에서는 빈 배열을 사용합니다. data.model="default"는 해당 단계의 기본 모델을 사용한다는 뜻이에요. is_default=True는 실행할 설정 ID를 생략했을 때 이 버전을 쓰도록 지정합니다. 이 예제에서는 반환된 config_id를 직접 지정해 실행해요.
3. 청구서 업로드하기
샘플 청구서를 내려받아 업로드하면 파일 ID를 받아요. 실행할 때는 파일을 다시 보내는 대신 이 ID를 사용합니다.
업로드 응답 일부:
반환된 file_id를 다음 실행 요청에 사용해요.
4. 실행 요청하기
실행 작업(Job)은 워크플로우에 문서를 보내 처리하는 요청 한 번을 뜻해요. 앞에서 받은 세 ID로 작업을 시작합니다.
Python에서는 SDK 기본 인자가 아닌 Studio의 config_id를 extra_body로 전달해요. cURL에서는 같은 필드를 JSON 본문에 직접 넣습니다.
실행 요청의 model에는 AI 모델 이름이 아니라 워크플로우 ID를 넣어요. config_id는 저장한 설정, file_id는 처리할 문서를 선택합니다. background=True이므로 처리가 끝나기 전에 작업 ID가 먼저 돌아옵니다. include=["last"]는 마지막 단계의 결과를 받는 옵션이며, 이 예제에서는 추출 결과를 뜻해요.
5. 결과 확인하기
작업 ID로 현재 상태와 결과를 조회해요. status가 in_progress이면 잠시 후 같은 조회 요청을 다시 보내세요. completed가 되면 output[].content[].text에 추출 결과가 JSON 문자열로 들어 있어요.
완료된 응답의 일부예요. 모델 출력에 따라 값은 달라질 수 있습니다.
failed 또는 cancelled이면 응답의 error를 확인하세요. 상태별 의미는 실행과 결과 확인에서 볼 수 있어요.
다음 문서에도 재사용하기
workflow_id와 config_id를 보관하세요. 새 청구서에는 3~5단계인 업로드 → 실행 → 결과 조회만 반복하면 돼요. 워크플로우와 설정을 매번 새로 만들 필요는 없습니다. 추출할 항목을 바꾸고 싶다면 새 설정 버전을 저장하면 되고, 이전 설정도 다시 사용할 수 있어요.
Studio의 기존 워크플로우 실행하기
Studio에서 워크플로우를 열고 설정을 저장한 뒤 오른쪽 위 더보기(⋯) → 코드를 선택하세요. 이 화면의 Agent ID(워크플로우 ID)와 Config ID(설정 ID)를 복사할 수 있어요.
1단계처럼 client를 초기화하고 복사한 값을 workflow_id, config_id에 넣은 뒤 3단계부터 진행하면 됩니다.