추론 | AGTCloud API Docs

복잡한 작업의 추론 수준을 설정하고 결과, 요약 및 Usage를 올바르게 읽습니다.

Reasoning은 다단계 분석, 복잡한 제약, 수학적 유도, 코드 설계 또는 도구 협력이 필요한 작업에 적합합니다. 추론 모델은 일반적으로 추론 수준을 조절할 수 있으며 추론 요약, Thinking Block 또는 관련 Usage를 반환할 수 있습니다. 구체적인 형식은 모델과 프로토콜에 따라 달라집니다.

단순 분류, 형식 변환 또는 짧은 질의응답에서는 추론 수준을 높여도 업무 결과가 개선되지 않을 수 있으며 응답 시간과 Token 사용량이 늘어날 수 있습니다.

추론 기능은 모든 프로토콜에 공통된 하나의 필드가 아닙니다

Chat, Responses, Anthropic Messages 및 Gemini는 추론 설정, 공개 결과와 여러 턴의 상태를 서로 다르게 표현합니다. 한 프로토콜의 필드를 다른 프로토콜에 그대로 복사해서는 안 됩니다.

사용 시점

작업	사용 권장 사항
여러 제약이 있는 설계 및 복잡한 분석	추론 지원 모델을 선택하고 낮은 수준 또는 기본 수준부터 평가합니다
수학, 코드 및 논리 문제	최종 답변도 검증하며 추론 수준을 결과의 정확성과 동일시하지 않습니다
도구 호출 워크플로	프로토콜에 필요한 호출, 결과 및 상태 구조를 유지하고 최대 반복 횟수를 설정합니다
짧은 재작성, 추출 및 분류	일반 모델이나 낮은 추론 수준부터 테스트하여 불필요한 비용을 줄입니다

먼저 모델 목록에서 현재 계정의 사용 가능한 모델, 프로토콜 및 기능 태그를 확인합니다. 예시의 MODEL_ID는 해당 추론 설정을 지원하며 현재 계정에서 사용할 수 있는 모델로 바꿔야 합니다.

Responses에서 추론 수준 설정

Responses의 추론 설정은 reasoning 객체에 있습니다:

curl 'https://api.agtcloud.cn/v1/responses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "model": "MODEL_ID",
    "input": "두 데이터베이스 마이그레이션 방안을 비교하고 선택 근거를 제시해 주세요.",
    "reasoning": {
      "effort": "medium",
      "summary": "auto"
    }
  }'

effort는 추론 수준을 조절하고, summary는 프로토콜이 공개를 허용하는 추론 요약을 요청합니다. 사용 가능한 값과 적용 여부는 모델에 따라 달라집니다. 전체 정의는 Responses Reference를 확인합니다.

프로토콜별 추론 표현

Chat은 reasoning_effort로 추론 수준을 요청할 수 있습니다. 응답이 추론 Token 정보를 제공하면 일반적으로 Usage의 완료 상세 정보에 기록되며, 최종 답변은 여전히 Assistant Message에서 읽습니다.

{
  "model": "MODEL_ID",
  "messages": [
    {"role": "user", "content": "이 배포 방안의 주요 위험을 분석해 주세요."}
  ],
  "reasoning_effort": "medium"
}

예시 값은 필드 위치를 설명할 뿐, 모든 모델이 동일한 수준이나 예산을 허용한다는 뜻은 아닙니다. 각각 Chat Completions, Anthropic Messages 및 Gemini Generate Content 레퍼런스를 확인합니다.

최종 답변과 공개 추론 정보 읽기

애플리케이션은 일반적으로 다음 내용을 각각 처리해야 합니다:

최종 답변: 실제로 사용자에게 보여주거나 후속 업무로 전달할 콘텐츠입니다.
추론 요약 또는 Thinking Block: 프로토콜과 모델이 명시적으로 반환할 때만 읽으며, 모델의 전체 내부 사고 과정과 같다고 가정하지 않습니다.
Usage: 입력, 최종 출력 및 추론 Token을 기록하며 필드 위치는 프로토콜에 따라 다릅니다.
중지 또는 미완료 상태: 출력 예산, 콘텐츠 정책, 취소 또는 오류로 답변이 미완료되었는지 판단합니다.

업무에 최종 결론만 필요하다면 공개 추론 내용을 영구 저장할 필요는 없습니다. 저장 전에 개인정보, 로그 범위 및 데이터 보관 정책도 평가해야 합니다.

Streaming과 도구 호출

스트리밍 응답은 추론 증분과 최종 텍스트 증분을 별도로 반환할 수 있으므로 독립된 버퍼를 사용합니다.
도구 호출 전후에 프로토콜 상태나 Thinking Block이 나타날 수 있으므로 최종 텍스트만 보관해서는 안 됩니다.
도구 실행에는 여전히 Tool Calling의 매개변수 검증, 권한 및 멱등성 요구 사항을 적용합니다.
이어서 생성할 때는 대상 프로토콜이 요구하는 이력 구조만 전달하며 서명, 호출 ID 또는 불투명한 상태를 임의로 바꾸지 않습니다.

전체 스트리밍 처리 방법은 Streaming을 확인합니다.

출력 예산 설계

추론 Token과 표시되는 답변이 함께 출력 예산을 사용할 수 있습니다. 예산이 너무 적으면 분석이 끝나도 완전한 최종 답변을 출력할 공간이 부족할 수 있습니다.

운영 애플리케이션에서는 다음을 함께 확인해야 합니다:

최종 답변의 완전성;
중지 또는 미완료 이유;
추론 및 표시되는 출력의 Usage;
추론 수준별 품질, 지연 시간 및 비용;
도구 호출 루프가 허용된 횟수와 전체 시간 제한 내에 끝나는지 여부.

운영 전 확인 사항

현재 계정에서 대상 모델을 사용할 수 있으며 해당 추론 API와 요청 필드를 확인했습니다.
애플리케이션은 대상 프로토콜이 허용하는 추론 필드만 보냅니다.
최종 답변, 공개 추론 정보 및 Usage를 각각 처리합니다.
스트리밍, 여러 턴 및 도구 호출에서 필요한 프로토콜 상태를 유지합니다.
출력 예산 부족, 거부, 시간 초과 및 불완전한 응답에 명확한 처리 분기가 있습니다.
추론 강도, 요약 또는 공개 Thinking을 정확성 보장으로 설명하지 않습니다.

요청이 실패하면 오류 및 문제 해결을 참고하고, 모델이나 프로토콜을 변경하기 전에 프로토콜 선택을 확인합니다.

추론