Chat Completions → Responses

Chat Completions는 messages와 choices로 대화를 구성하고 Responses는 input, Typed Items 및 output으로 입력, 도구 호출 및 결과를 표현합니다. 마이그레이션에서는 엔드포인트뿐 아니라 입력 구조, 응답 파싱, 도구 루프 및 스트리밍 상태 머신을 조정해야 합니다.

마이그레이션 필요 여부

Responses로 마이그레이션하기에 적합한 경우입니다.

• 새 프로젝트에서 통합된 Typed Input과 Output Items를 사용하려는 경우입니다.
• previous_response_id 등의 다중 턴 상태 기능이 필요한 경우입니다.
• Responses가 지원하는 내장 도구가 필요한 경우입니다.
• 애플리케이션이 Item 유형에 따라 텍스트, 도구 호출 및 기타 출력을 처리하려는 경우입니다.

Chat Completions를 계속 사용할 수 있는 경우입니다.

• 기존 애플리케이션이 messages, choices 및 Chat Delta에 안정적으로 의존합니다.
• 대상 모델 또는 필요한 도구가 Chat Completions만 지원합니다.
• 도구, 다중 턴 및 Streaming을 다루는 회귀 테스트가 아직 충분하지 않습니다.
• 마이그레이션의 이점이 응답 파싱과 상태 관리 변경 비용을 상쇄하지 못합니다.

핵심 변경

최소 요청 Before / After

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "간결하고 정확하게 답변해 주세요."
    },
    {
      "role": "user",
      "content": "AGTCloud를 한 문장으로 소개해 주세요."
    }
  ]
}

OpenAI SDK를 사용할 때 Client의 Base URL은 여전히 https://api.agtcloud.cn/v1입니다. 메서드는 client.chat.completions.create(...)에서 client.responses.create(...)로 변경합니다. 전체 Python 및 TypeScript 초기화 방식은 OpenAI SDK를 확인합니다.

응답 읽기 마이그레이션

Chat Completions는 보통 첫 번째 Choice에서 어시스턴트 메시지를 읽습니다.

choices[0].message.content

Responses는 순서가 있는 output[]을 반환합니다. 메시지, 함수 호출, 검색 호출 또는 기타 Item이 함께 포함될 수 있습니다. SDK의 output_text로 집계된 텍스트를 읽을 수 있지만 도구 또는 기타 출력을 처리하려면 전체 output을 순회해야 합니다.

response.output_text
response.output[]

다중 턴 상태 마이그레이션

previous_response_id를 사용해도 이전 턴의 instructions가 자동 상속되지 않습니다. 각 턴에서 애플리케이션의 필요에 따라 지시를 다시 설정해야 합니다.

마이그레이션 후 동일한 기록을 전부 재전송하면서 previous_response_id로 다시 참조하지 않습니다. 컨텍스트가 중복될 수 있습니다.

Function Calling 마이그레이션

도구 정의

Chat Completions는 함수 정의를 tools[].function에 포함합니다.

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "도시 날씨 조회",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string" }
      },
      "required": ["city"]
    }
  }
}

Responses는 함수 정보를 Function Tool 객체에 직접 포함합니다.

{
  "type": "function",
  "name": "get_weather",
  "description": "도시 날씨 조회",
  "parameters": {
    "type": "object",
    "properties": {
      "city": { "type": "string" }
    },
    "required": ["city"]
  }
}

결과 전달

• Chat: assistant.tool_calls[]에서 호출을 읽고 tool_call_id가 있는 Tool Message를 추가합니다.
• Responses: output[]에서 function_call을 읽은 뒤 function_call_output을 보내며 call_id는 원래 호출과 일치해야 합니다.

어떤 프로토콜이든 함수는 애플리케이션이 실행합니다. 검증되지 않은 매개변수를 직접 실행하거나 도구 오류를 정상 결과로 위장하지 않습니다.

Streaming 마이그레이션

Chat Completions는 각 Chunk의 choices[].delta로 증분을 반환하며 보통 [DONE]으로 끝납니다.

Responses는 다음과 같은 이름이 있는 이벤트를 사용합니다.

• response.created;
• response.output_item.added;
• response.content_part.added;
• response.output_text.delta;
• response.output_text.done;
• response.completed.

마이그레이션에서는 기존의 텍스트 결합 전용 로직을 이벤트 분배기로 바꿉니다. 이벤트 유형에 따라 처리한 뒤 output_index, content_index, item_id 등의 식별자로 해당 상태를 갱신합니다.

Structured Outputs 마이그레이션

Chat Completions는 출력 형식 설정을 response_format에, Responses는 해당 설정을 text.format에 포함합니다. 마이그레이션할 때 다음을 함께 수정해야 합니다.

1. 요청 필드 위치입니다.
2. JSON Schema 래핑 구조입니다.
3. SDK의 파싱 보조 메서드입니다.
4. 거부, 불완전 응답 및 Schema 검증 실패 처리입니다.

자세한 필드는 Chat Completions와 OpenAI Responses를 각각 확인합니다.

Web Search 마이그레이션

두 프로토콜의 검색 진입점은 다릅니다.

• Chat Completions는 web_search_options를 사용하며 검색을 지원하는 모델을 선택해야 합니다.
• Responses는 tools에서 지원되는 Web Search Tool을 활성화하며 검색 호출 Item과 인용을 반환할 수 있습니다.

도메인 필터링, 출처 목록, 사용자 위치 및 실시간 인터넷 접근 등의 설정은 선택한 프로토콜과 모델에 따라 달라집니다. 전체 예시는 OpenAI Web Search를 확인합니다.

Usage, 오류 및 중단

모니터링과 청구 읽기 로직을 마이그레이션할 때 최소한 다음을 조정합니다.

HTTP 상태 코드, 오류 객체 및 Request ID도 유지합니다. SDK 오류 텍스트만 수집하지 않습니다. 애플리케이션 로그에서 인증 실패, 모델 미표시, 요청 제한, 서비스 오류 및 연결 중단을 구분할 수 있어야 합니다.

단계별 마이그레이션

회귀 및 폴백 체크리스트

• 일반 텍스트, 빈 출력, 거부, 불완전 및 실패 상태입니다.
• 단일 도구, 다중 도구, 도구 실패 및 매개변수 검증 실패입니다.
• 무상태 기록 재전송 및 previous_response_id입니다.
• Streaming 정상 완료, 스트림 중단 및 중복 이벤트입니다.
• Structured Outputs 검증 실패입니다.
• Usage, 오류 정보, Request ID, 타임아웃 및 요청 제한입니다.
• 대상 모델이 Responses 기능을 지원하지 않을 때 Chat Completions로 전환할 수 있어야 합니다.

운영 전환 전에 Chat과 Responses에 독립된 설정과 통제 가능한 스위치를 유지합니다. 업무 지표, 로그 및 오류 처리의 안정성을 확인한 뒤 기존 파싱 경로를 정리합니다.

다음 단계

• OpenAI SDK로 Python 또는 TypeScript Client를 설정합니다.
• 텍스트 및 대화에서 Responses의 일상적인 호출 흐름을 이해합니다.
• OpenAI Responses에서 전체 필드 및 응답을 확인합니다.
• 호출 오류가 발생하면 오류 및 문제 해결을 확인합니다.