TokenLab

핵심 가이드

Structured Outputs & Tool Calling

JSON을 반환하거나 모델이 애플리케이션 내에서 함수를 호출하도록 설정

Structured output(구조화된 출력)은 모델에 JSON을 요청합니다. Tool calling(도구 호출)은 모델이 애플리케이션에서 실행할 함수를 요청할 수 있게 합니다. 사용 가능한 필드는 API 형식과 모델에 따라 다르므로, 대화 전체에서 하나의 형식을 유지하고 모델이 생성한 모든 값을 애플리케이션에서 검증하십시오.

API 형식 선택

필요 사항API필드
이식 가능한 JSON 객체 응답/v1/chat/completionsresponse_format: {"type": "json_object"}
OpenAI 호환 함수 호출/v1/chat/completionstools: [{ "type": "function", "function": ... }]
OpenAI 응답 도구/v1/responsesResponses tools, tool_choice, 및 text 필드
Claude 네이티브 도구 사용 또는 사고/v1/messagesAnthropic Messages 도구 스키마
Gemini 함수 선언 또는 내장 도구/v1beta/models/:model:generateContentGemini 네이티브 tools 및 콘텐츠 파트

내장 도구는 해당 도구를 문서화하는 API 형식에서만 사용하십시오. TokenLab은 이러한 도구를 형식 간에 변환하지 않습니다.

JSON 모드

여러 채팅 모델에서 작동하는 JSON 객체를 얻으려면 Chat Completions JSON 모드를 사용하십시오:

{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with city and weather."
    }
  ],
  "response_format": { "type": "json_object" }
}

JSON 모드를 지원하는 모델은 GET /v1/models의 capabilities에 json-mode를 나열합니다. Chat Completions는 text와 json_object를 허용합니다. json_schema와 strict는 모델 및 형식별로 다르므로, 선택한 모델이 지원을 문서화한 경우에만 사용하십시오.

반환된 JSON은 항상 서버에서 파싱하고 검증하십시오. JSON 모드가 애플리케이션 수준의 스키마 검증을 대체하지는 않습니다.

도구 호출 완료

TokenLab은 함수 이름과 인수를 반환하며, 애플리케이션이 이를 실행합니다:

  1. 메시지와 도구 정의를 함께 보냅니다.
  2. tool_calls, function_call, Anthropic tool_use 또는 Gemini 함수 호출 파트에 대한 모델 응답을 읽습니다.
  3. 자체 백엔드에서 도구를 실행합니다.
  4. 동일한 API 형식으로 도구 결과를 추가합니다.
  5. 모델이 최종 답변을 반환할 때까지 대화를 계속합니다.

도구 호출과 최종 답변이 완료될 때까지 동일한 API 형식을 유지하십시오. 네 가지 형식은 도구 상태를 서로 다르게 표현합니다.

Chat Completions 예시

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {
        "role": "user",
        "content": "Extract name and email as JSON. If needed, look up the customer."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Look up a customer by email",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

유용한 스키마 작성

  • 스키마를 작고 명확하게 유지하십시오. 중첩된 대규모 스키마는 토큰을 증가시키고 신뢰성을 떨어뜨립니다.
  • 제품 운영에 필수적인 값에는 필수 필드(required fields)를 우선적으로 사용하십시오.
  • UI나 백엔드가 의존하는 닫힌 집합에는 enum을 사용하십시오.
  • 모델이 형태를 잡는 데 어려움을 겪는 경우 프롬프트에 예시를 포함하십시오.
  • 필드가 지원되지 않는 경우, 해당 필드를 제거하거나 이를 문서화하는 API 형식을 사용하십시오.

도구 실행 전 주의사항

  • API 형식, 모델, 도구 이름 및 스키마 필드 이름을 기록하십시오.
  • 부작용(side effect)을 실행하기 전에 도구 인수를 검증하십시오.
  • 도구 실행 전 자체 권한 확인을 적용하십시오.
  • 클라이언트 재시도로 인해 동일한 도구 호출이 반복될 수 있으므로 도구 실행을 멱등성(idempotent) 있게 만드십시오.
  • 도구가 반환한 비밀 정보를 모델이 볼 수 있는 메시지에 기록하지 마십시오.

API 참조

주제참조
다중 형식 APIMulti-Format API
채팅 완료 생성채팅 완료 생성 (Create Chat Completion)
응답 생성응답 생성
메시지 생성메시지 생성 (Create Message)
Gemini 콘텐츠 생성Generate Gemini Content

이 페이지의 내용