대화 보완 API (Chat Completions)

대화 보완 API (Chat Completions)

LLM 호출의 가장 기본이 되는 길이 하나 있어요. 바로 선택한 모델과 대화를 주고받는 대화 보완(Chat Completions) 엔드포인트인데요, 텍스트·이미지·오디오·비디오·파일을 아우르는 다중모달 입력과 스트리밍/비스트리밍 출력, 샘플링·온도·최대 토큰·도구 호출 설정을 모두 이 한 곳에서 다룹니다. 이 글에서는 요청을 구성하는 핵심 파라미터와 응답 구조를 살펴볼게요.

출처: 对话补全 (Chat Completions) - 智谱开放平台 문서

엔드포인트와 기본 호출

기본 서버는 https://open.bigmodel.cn/api/이고, 대화 추론은 POST 방식으로 다음 경로를 호출합니다.

POST https://open.bigmodel.cn/api/paas/v4/chat/completions

요청은 JSON 형식이며, model과 messages는 반드시 포함해야 해요. model에는 glm-5.3 같은 모델 코드를, messages에는 system·user·assistant·tool 역할의 대화 목록을 배열로 넣습니다.

주요 요청 파라미터

파라미터 타입 필수 설명
model String 예 호출할 모델 코드
messages List 예 모델 프롬프트 입력이 되는 대화 메시지 목록
request_id String 아니오 요청을 구분하는 고유 ID, 미지정 시 플랫폼이 자동 생성
temperature Float 아니오 출력 무작위성 제어, 범위 [0.0, 1.0], 기본 0.95
top_p Float 아니오 누적확률 샘플링, 범위 [0.0, 1.0], 기본 0.7
max_tokens Integer 아니오 모델 출력의 최대 토큰 수
stop List 아니오 해당 문자열을 만나면 생성을 멈춤
tools List 아니오 모델이 호출할 수 있는 도구 목록
tool_choice String/Object 아니오 어느 함수를 호출할지 제어, 기본 auto
user_id String 아니오 최종 사용자 고유 ID, 남용 방지용으로 6~128자

temperature가 높을수록 창의적이고 낮을수록 결정적인데, GLM-5.2 이상의 추론 모델은 기본적으로 생각을 켜고 동작하므로 온도만으로 출력을 무작위하게 만들 수는 없다는 점도 기억해 두면 좋아요.

메시지 역할

  • system — 모델의 행동과 톤을 지정하는 시스템 프롬프트.
  • user — 사용자가 보낸 입력.
  • assistant — 모델의 이전 응답. content 또는 tool_calls 중 하나를 담아요.
  • tool — 도구를 호출한 뒤의 반환 결과로, tool_call_id로 어떤 호출에 대한 결과인지 연결합니다.

도구 정의 (tools)

도구는 크게 세 종류를 지원합니다.

  • web_search — search_engine(기본 search_std)과 검색 결과 개수, 도메인 필터, 검색 범위 등을 지정. 지원 엔진은 search_std, search_pro, search_pro_sogou, search_pro_quark, search_pro_jina, search_pro_bing.
  • function — 함수 호출. description과 parameters(JSON Schema)로 함수를 정의해요.
  • retrieval — 지식 베이스 검색. prompt_template으로 {{ question }}·{{ knowledge }} 자리표시자를 쓸 수 있습니다.

함수 호출을 쓸 때는 do_sample을 끄거나 temperature·top_p를 낮추면 성공률이 높아져요.

응답 구조와 스트리밍

정상 응답은 id, created, model, choices, usage를 돌려줍니다. choices[0].message.content가 답변 본문이에요. stream: true로 설정하면 SSE(Server-Sent Events) 형식으로 델타가 조각조각 도착하고, choices[0].delta에 증분 텍스트가 담깁니다.

비동기 호출

긴 작업은 비동기로도 처리할 수 있어요. POST /paas/v4/async/chat/completions로 생성하면 task_status가 PROCESSING/SUCCESS/FAIL로 나오고, GET /paas/v4/async-result/{id}로 결과를 조회합니다.

더 알아보기 (Learn more)