워크플로우는 여러 문서에 반복해서 적용할 문서 처리 절차예요. 이름을 붙여 만든 뒤 처리 단계를 추가하고 연결해 첫 설정 버전을 저장합니다.
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를 직접 지정해 실행해요.
저장한 뒤에는 문서를 업로드하고 워크플로우를 실행하세요. 저장된 워크플로우를 변경하려면 워크플로우 활용하기를 확인하세요.
필요한 처리 단계 추가하기
단계 설정 읽는 법
| 필드 | 의미 |
|---|---|
name | 다음 단계를 연결할 때 쓰는 고유 이름이에요. |
type | document-parse 같은 처리 종류예요. |
data | 모델·추출 항목 등 해당 단계의 설정이에요. |
is_first | 첫 단계 하나만 true로 지정해요. |
next_steps | 이어 실행할 단계 이름과 필요한 경우 실행 조건이에요. |
아래 JSON은 Config의 steps 목록에 넣는 개별 단계 예시예요. 완성된 요청이 아니므로 필요한 단계를 연결해 저장하세요. 이 가이드는 주요 처리 종류 여섯 가지를 다룹니다.
Parse
Parse는 문서 내용을 읽어요. 사용할 때는 첫 단계로 두세요. model="default"는 이 처리 종류의 기본 모델을 선택한다는 뜻입니다.
Classify
Classify는 청구서·영수증처럼 문서 종류를 분류해요. json_schema에 분류할 이름을 적으며, 예제에서는 invoice와 receipt를 사용합니다. split=true로 설정하면 종류별로 문서를 나눠 다음 단계를 실행해요.
Extract
Extract는 지정한 값을 구조화된 데이터로 추출해요. JSON Schema는 추출할 항목 이름과 값의 종류를 적은 설정입니다. 글자는 string, 금액은 number로 표현해요. 한 실행 경로에는 Extract를 최대 하나 넣을 수 있습니다.
Instruct
Instruct는 문서 요약이나 문서에 관한 질문처럼 글로 작성한 지시를 수행해요. queries에 비어 있지 않은 지시문을 넣습니다.
Merge
Merge는 Classify에서 나눈 문서를 모아 다음 단계가 함께 처리하도록 해요. 시작 단계로 사용할 수 없고 한 경로에 한 번만 넣습니다. 다음 단계는 조건 없이 하나만 연결하며 Merge로 끝나면 next_steps=null을 사용해요.
Validate
Validate는 앞선 결과가 정해 둔 규칙에 맞는지 확인해요. 각 규칙에 고유한 이름, 조건, 중요도를 지정합니다. error는 반드시 통과해야 하는 규칙, warning은 주의가 필요한 규칙이에요. 필수 규칙에 실패하면 red, 주의 규칙만 실패하면 yellow, 모두 통과하면 green입니다. 예제는 앞에 있는 Parse 단계에서 페이지를 하나 이상 읽었는지 확인하며, gt는 오른쪽 값보다 크다는 뜻이에요.
처리 단계 연결하기
Parse 다음에 Extract를 실행하려면 Parse의 next_steps를 아래 배열로 설정하세요. step_name은 다음 단계의 name과 같아야 해요. is_first=true는 Parse에만 지정합니다.
문서 종류별로 나누는 Classify 뒤에서 청구서만 Extract로 보내려면 아래처럼 연결하세요. 분류 결과인 text가 위에서 정한 종류 이름 invoice와 같은지 비교하는 조건이에요.
앞선 단계로 되돌아가는 반복 연결은 허용하지 않아요. 선택한 모델은 API 키로 사용할 수 있어야 하며 model_access_denied는 모델 권한이 없다는 뜻입니다. 설정 저장이 거부되면 입력 오류 명세를 확인하세요.