코드로 더 세밀하게
다뤄봅니다

pip install --upgrade openai requests

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["UPSTAGE_API_KEY"],
    base_url="https://api.upstage.ai/v1",
)

MODEL = "solar-pro4"   # AI Initiative 지원 모델

messages = [
    {"role": "user", "content": "제가 좋아하는 색은 초록색이에요."}
]

first = client.chat.completions.create(model=MODEL, messages=messages)
messages.append({"role": "assistant", "content": first.choices[0].message.content})

# 두 번째 질문. 앞의 내용을 함께 보냈기 때문에 답할 수 있습니다
messages.append({"role": "user", "content": "제가 좋아하는 색이 뭐라고 했죠?"})

second = client.chat.completions.create(model=MODEL, messages=messages)
print(second.choices[0].message.content)

import json

response = client.chat.completions.create(
    model=MODEL,
    messages=[{
        "role": "user",
        "content": "이 문의를 분류하고 짧은 답변 초안을 써 주세요: 구독료가 두 번 결제되었습니다."
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "inquiry",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "category": {
                        "type": "string",
                        "enum": ["결제", "기술", "계정"],
                        "description": "문의가 속한 분류"
                    },
                    "urgent": {
                        "type": "boolean",
                        "description": "즉시 대응이 필요한지 여부"
                    },
                    "reply": {
                        "type": "string",
                        "description": "고객에게 보낼 짧은 답변"
                    }
                },
                "required": ["category", "urgent", "reply"],
                "additionalProperties": False
            }
        }
    }
)

if response.choices[0].finish_reason != "stop":
    raise RuntimeError("응답이 중간에 끊겼습니다. max_tokens 를 늘리거나 다시 시도해 주세요.")

result = json.loads(response.choices[0].message.content)
print(result["category"], result["urgent"])
print(result["reply"])

tools = [{
    "type": "function",
    "function": {
        "name": "get_budget",
        "description": "부서와 연도로 예산 집행 현황을 조회합니다.",
        "parameters": {
            "type": "object",
            "properties": {
                "department": {"type": "string", "description": "부서명"},
                "year": {"type": "integer", "description": "조회 연도"}
            },
            "required": ["department", "year"],
            "additionalProperties": False
        }
    }
}]

messages = [{"role": "user", "content": "교육팀의 2026년 예산 집행률을 알려 주세요."}]

response = client.chat.completions.create(
    model=MODEL,
    messages=messages,
    tools=tools,
    tool_choice="auto",
)

import json

tool_calls = response.choices[0].message.tool_calls

if tool_calls:
    messages.append(response.choices[0].message)

    for call in tool_calls:
        # 1) 허용한 함수가 맞는지 확인합니다
        if call.function.name != "get_budget":
            raise ValueError(f"허용되지 않은 도구입니다: {call.function.name}")

        # 2) 값이 올바른 형태인지 확인합니다
        args = json.loads(call.function.arguments)
        department = args.get("department")
        year = args.get("year")
        if not isinstance(department, str) or not department.strip():
            raise ValueError("department 는 비어 있지 않은 문자열이어야 합니다")
        if not isinstance(year, int):
            raise ValueError("year 는 정수여야 합니다")

        # 3) 확인이 끝난 뒤에 실행합니다
        result = get_budget(department=department, year=year)

        messages.append({
            "tool_call_id": call.id,
            "role": "tool",
            "name": call.function.name,
            "content": json.dumps(result, ensure_ascii=False),
        })

    final = client.chat.completions.create(model=MODEL, messages=messages)
    print(final.choices[0].message.content)

import os
import requests

url = "https://api.upstage.ai/v1/document-digitization"
headers = {"Authorization": f"Bearer {os.environ['UPSTAGE_API_KEY']}"}

with open("sample.pdf", "rb") as f:
    response = requests.post(
        url,
        headers=headers,
        files={"document": f},
        data={"model": "document-parse", "ocr": "force"},
    )

result = response.json()

print(result["content"]["html"][:500])   # 구조가 살아 있는 결과
print(result["usage"]["pages"], "페이지 처리")

import time
import glob

results = {}

for path in glob.glob("documents/*.pdf"):
    try:
        with open(path, "rb") as f:
            response = requests.post(
                url,
                headers=headers,
                files={"document": f},
                data={"model": "document-parse", "ocr": "force"},
            )

        if response.status_code == 429:
            time.sleep(3)          # 기준을 넘었으니 잠시 기다립니다
            continue

        response.raise_for_status()
        results[path] = response.json()["content"]["html"]
        print(f"완료: {path}")

    except Exception as e:
        print(f"실패: {path} — {e}")

    time.sleep(1)                  # 초당 1건 기준을 지킵니다

import json

# 1단계. 문서를 글로 바꿉니다
with open("receipt.pdf", "rb") as f:
    parsed = requests.post(
        url, headers=headers,
        files={"document": f},
        data={"model": "document-parse", "ocr": "force"},
    ).json()

document_text = parsed["content"]["html"]

# 2단계 + 3단계. 값을 뽑고 기준에 비추어 판단합니다
response = client.chat.completions.create(
    model=MODEL,
    messages=[{
        "role": "user",
        "content": f"아래 영수증에서 상호명·발행일·총액을 찾고, "
                   f"총액이 100000원을 넘으면 보류로 판단해 주세요.\n\n{document_text}"
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "receipt",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "store_name":   {"type": ["string", "null"], "description": "영수증 상단의 상호명"},
                    "issued_date":  {"type": ["string", "null"], "description": "발행 일자"},
                    "total_amount": {"type": ["integer", "null"], "description": "부가세 포함 최종 결제 금액"},
                    "decision":     {"type": "string", "enum": ["승인", "보류", "확인필요"]},
                    "reason":       {"type": "string", "description": "그렇게 판단한 근거 한 문장"}
                },
                "required": ["store_name", "issued_date", "total_amount", "decision", "reason"],
                "additionalProperties": False
            }
        }
    }
)

print(json.loads(response.choices[0].message.content))

https://console.upstage.ai/api/docs/for-agents/raw

위 주소를 먼저 읽어 주세요.
Upstage API 는 이 문서에 적힌 스펙만 사용하고,
기억에 있는 내용으로 채우지 말아 주세요.

# 이 프로젝트의 Upstage API 규칙

## 먼저 읽을 것
- https://console.upstage.ai/api/docs/for-agents/raw
- 기억에 의존하지 말고 위 문서의 스펙만 사용한다.

## 반드시 지킬 것
- 언어 모델은 `solar-pro4` 만 쓴다.
  `solar-mini` 등 그 밖의 Solar 계열은 금지. AI Initiative 지원 범위 밖이라 호출이 실패한다.
  (`solar-pro2`, `solar-pro3` 도 지원 범위지만 새로 만들 때는 `solar-pro4` 로 통일한다.)
- 문서 처리는 `document-parse` 만 쓴다.
  `information-extract`, `document-classify`, 임베딩 계열
  (`solar-embedding-2-query`, `solar-embedding-2-passage`)은 금지. 크레딧이 차감된다.
- 항목 추출과 문서 분류는 별도 제품을 쓰지 않는다.
  Document Parse 로 텍스트를 만든 뒤 Solar 의 structured outputs 로 처리한다.

## 주소
- Solar          : https://api.upstage.ai/v1  (OpenAI 호환, openai 라이브러리)
- Document Parse : https://api.upstage.ai/v1/document-digitization  (multipart/form-data)
- 두 제품은 응답 구조가 다르다.
  Solar 는 choices[0].message.content, Document Parse 는 content.html / elements[].

## 키
- 키를 코드에 직접 적지 않는다. 항상 os.environ["UPSTAGE_API_KEY"] 로 읽는다.
- 키 값을 로그, 주석, 커밋에 남기지 않는다.

## 한도
- Tier 0 기준 분당 100회 · 50,000 토큰. Document Parse 는 초당 1건.
- 반복 호출에는 호출 간 대기와 429 재시도를 반드시 넣는다.

## 결과 처리
- structured outputs 는 strict: true, additionalProperties: false,
  모든 항목을 required 에 넣는다. 비어 있을 수 있는 항목은 ["string", "null"] 로 연다.
- 응답을 읽기 전에 finish_reason == "stop" 인지 확인한다.
- 금액과 날짜는 사람이 확인하는 단계를 남긴다.

# 내 업무용 형식 설계

## 입력
- 문서 형식:
- 한 번에 처리할 건수:
- Document Parse 가 필요한가요 (예 / 아니오):

## 뽑을 항목
| 항목 이름(영문) | 설명 | 형태 | 비어 있을 수 있나요 |
|---|---|---|---|
|  |  |  |  |
|  |  |  |  |
|  |  |  |  |

## 판단 값
- 고를 수 있는 값 (enum):
- 각 값의 기준을 숫자와 조건으로:

## 검증
- 사람이 반드시 확인할 항목:
- 값이 이상할 때 어떻게 처리하나요:

## 실패 처리
- 429 를 받으면:
- 값이 비어 오면:

## 뽑을 항목
| 항목 이름        | 설명                          | 형태  | 비어 있을 수 있나요 |
| applicant_org   | 신청 기관명                    | 문자  | 아니오 |
| project_title   | 사업명                        | 문자  | 아니오 |
| requested_amount| 요청 금액 (원 단위 정수)        | 정수  | 예 |
| attachments     | 첨부 서류 이름 목록             | 배열  | 예 |

## 판단 값
- enum: ["접수가능", "보완요청", "확인필요"]
- 접수가능: 필수 항목이 모두 있고 요청 금액이 5천만 원 이하
- 보완요청: 필수 첨부 서류가 하나라도 빠짐
- 확인필요: 금액이나 기관명을 찾지 못함

## 검증
- 사람이 확인할 항목: requested_amount (금액은 항상 사람이 대조)
- 값이 이상할 때: 확인필요로 표시하고 담당자에게 전달

## 실패 처리
- 429 를 받으면: 3초 기다린 뒤 다시 시도, 세 번까지
- 값이 비어 오면: 확인필요로 표시하고 원문 페이지 번호를 함께 기록