Chat Completions API

가장 많이 사용되는 대화 API로, OpenAI Chat Completions 인터페이스와 완전히 호환됩니다.

POST/v1/chat/completions채팅 대화 생성

POST https://hub.lurus.cn/v1/chat/completions

스트리밍 응답

SSE로 토큰 단위 반환

Function Calling

모델이 당신의 함수를 호출하도록

멀티모달 Vision

텍스트와 이미지를 혼합 입력

모범 사례

Temperature / System Prompt / 멀티턴

---

요청 파라미터

필수

파라미터	타입	설명
model	string	모델 이름, 예: deepseek-chat, gpt-4o
messages	array	대화 메시지 배열, 아래 형식 참고

자주 쓰는 선택 파라미터

파라미터	타입	기본값	설명
temperature	number	1.0	무작위성(0–2). 코드/수학은 0.1, 창의적 글쓰기는 0.9
max_tokens	integer	—	최대 생성 토큰 수. 설정하지 않으면 모델이 결정
stream	boolean	false	스트리밍 출력Streaming스트리밍 응답으로, AI 모델이 전체 생성을 기다리지 않고 결과를 Token 단위로 반환하여 첫 글자 지연을 줄입니다.(SSE), 스트리밍 응답 참고
top_p	number	1.0	뉴클리어스 샘플링, 일반적으로 temperature와 둘 중 하나만 조정
stop	string/array	—	이 문자열을 만나면 생성 중단
n	integer	1	동시에 생성할 후보 응답 개수
user	string	—	사용자 식별자, 감사 로그에 사용

Messages 형식

[
  {"role": "system",    "content": "你是一位专业的技术顾问。"},
  {"role": "user",      "content": "什么是 RESTful API？"},
  {"role": "assistant", "content": "RESTful API 是…"},
  {"role": "user",      "content": "能举个例子吗？"}
]

역할	용도
system	AI의 행동, 어조, 제약을 설정. 배열의 첫 번째에 둠
user	사용자의 입력
assistant	AI의 응답. 멀티턴 대화 시 이전 응답을 포함해야 함

요청 본문(ChatCompletionRequest)과 메시지(Message)의 전체 필드 정의는 데이터 구조 레퍼런스를 참고하세요.

---

기본 예제

---

스트리밍 응답

stream: true로 설정하면 응답이 Server-Sent Events를 통해 토큰 단위로 반환되어 채팅류 애플리케이션에 적합합니다.

스트리밍 데이터 형식

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"落"},"index":0}]}
data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"叶"},"index":0}]}
...
data: [DONE]

TIP

마지막 data: [DONE]은 스트림의 종료를 의미하며, 이때 delta.content는 비어 있습니다.

---

Function Calling

AI가 당신이 제공한 함수를 언제 호출할지 결정하도록 하고, 구조화된 파라미터(Tool CallTool CallAI 모델이 추론 과정에서 검색이나 데이터베이스 조회 같은 외부 도구의 호출을 결정하고, 구조화된 호출 파라미터를 반환하는 것입니다.)를 반환합니다. 검색, 데이터베이스 조회, 외부 API 호출 등의 시나리오에 적합합니다.

작동 흐름

Function Calling 호출 흐름

graph LR; A[당신의 요청<br/>tools 정의 포함] --> B[모델 반환<br/>finish_reason: tool_calls]; B --> C[당신이 함수 실행<br/>결과를 role: tool로 전달]; C --> D[모델이 결과를 종합하여<br/>최종 답변 생성]

전체 예제: 날씨 조회

모델 지원

Function Calling은 모델의 지원이 필요합니다. gpt-4o, gpt-4o-mini, claude-3-5-sonnet 사용을 권장합니다. DeepSeek 계열도 지원하지만 파라미터 형식에 미세한 차이가 있으므로 테스트 시 검증에 주의하세요.

---

멀티모달 입력(Vision)

일부 모델은 이미지 내용을 이해할 수 있으며, content에 텍스트와 이미지를 혼합하여 입력합니다.

Vision을 지원하는 모델

gpt-4o, gpt-4o-mini, gemini-3-pro-preview, gemini-3-pro-image-preview

이미지 크기 제한: URL 이미지는 공인망에서 접근 가능해야 함; Base64는 장당 5 MB를 넘지 않을 것을 권장.

---

모범 사례

System Prompt 작성법

{
  "role": "system",
  "content": "你是一位专业客服。请用友好简洁的语气回答，每条回复不超过 150 字。如遇无法回答的问题，引导用户联系 support@lurus.cn。"
}

좋은 System Prompt에는: 역할 정의 + 어조 요구 + 길이 제한 + 경계 처리가 포함됩니다.

Temperature 설정 참고

시나리오	temperature	설명
코드 생성, 수학 계산	0.0–0.2	결정성이 높고 무작위성 감소
질의응답, 요약, 분류	0.3–0.6	정확하면서도 어느 정도 유연성 있음
창의적 글쓰기, 브레인스토밍	0.7–1.0	다양성이 강함
무작위 스토리, 롤플레잉	1.0–1.5	높은 창의성, 불안정할 수 있음

멀티턴 대화 관리

conversation = [
    {"role": "system", "content": "你是一位历史老师。"}
]

def chat(user_input: str) -> str:
    conversation.append({"role": "user", "content": user_input})
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=conversation,
        max_tokens=500
    )
    reply = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": reply})
    return reply

print(chat("秦始皇是谁？"))
print(chat("他有哪些重要成就？"))  # 模型能记住上文的"秦始皇"

컨텍스트 윈도우 관리

각 모델의 컨텍스트 길이는 제한적입니다(예: deepseek-chat은 64K tokens). 대화가 너무 길어지면 다음을 할 수 있습니다:

1. 가장 오래된 메시지를 잘라냄(system + 최근 N턴 유지)
2. 정기적으로 이전 대화를 요약하여 토큰 사용량 압축

---

오류 처리

자주 발생하는 상태 코드: 400 요청 형식 오류 → JSON 구조와 필수 파라미터 확인; 401 Key 무효/만료; 403 이 모델에 접근 권한 없음 → 관리자에게 문의; 429 속도 제한 초과 → 지수 백오프 재시도; 500/502 업스트림 모델 이상 → 재시도하거나 대체 모델로 전환. 전체 오류 코드와 재시도 전략은 오류 처리를 참고하세요.

---

다음 단계

오류 처리데이터 구조 / Schema인증API 개요지원하는 모델