대형 모델 API 인터페이스 파라미터 상세 설명: 요청 필드부터 응답 필드까지

요청의 구조

인터페이스 주소는 POST https://api.apidamoxing.com/v1/chat/completions이며, 인증 헤더는 Authorization: Bearer <key>입니다. 요청 본문은 JSON 형식이며 OpenAI의 채팅 완성 API와 호환됩니다. 일반적인 필드를 모두 사용한 전체 요청 예시를 먼저 살펴보겠습니다.

复制curl https://api.apidamoxing.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [
      {"role": "system", "content": "你是一位耐心的天文科普作者。"},
      {"role": "user", "content": "为什么月亮总是同一面朝向地球？"}
    ],
    "temperature": 0.7,
    "top_p": 0.9,
    "max_tokens": 400,
    "stop": ["###"]
  }'

여기서 model은 uncensored만 입력해야 합니다. 서비스에 제공되는 모델이 하나뿐이므로 선택지가 없기 때문입니다. GET /v1/models로 확인할 수 있습니다. 아래에서 필드별로 하나씩 설명하겠습니다.

전체를 읽으면 이러한 파라미터가 세 가지 범주로 나뉜다는 것을 알 수 있습니다: '무엇을 말할지' 결정하는 것(messages, tools), '어떻게 말할지' 결정하는 것(temperature, top_p), '얼마나 말할지, 언제 멈출지' 결정하는 것(max_tokens, stop, stream). 이 분류를 기억하면 낯선 필드를 마주했을 때 먼저 범주를 판단하여 용도를 대략 추측할 수 있습니다.

messages: 대화의 '기록장'

messages는 배열이며, 각 요소는 role과 content을 가집니다. 이를 페이지마다 기록되는 회의록으로 상상해 보세요. 모델은 매번 처음부터 다시 읽고 다음 페이지를 작성합니다. 모델은 이전에 무엇을 읽었는지 기억하지 않으므로, 다중 턴 대화에서는 역사가 필요하면 사용자가 전체를 제공해야 합니다.

일반적인 팁: 모델에게 특정 어조로 계속 쓰게 하려면 assistant 메시지를 직접 구성하여 역사에 넣을 수 있습니다. 프롬프트와 출력의 합계가 100,000 토큰을 초과하지 않도록 주의하세요. 역사가 길수록 공간을 더 많이 차지합니다.

구체적인 예를 들어보겠습니다. 고객 서비스 어시스턴트를 만들었다면, system에 "주문 관련 질문에만 답변하고, 답변은 3문장 이내로 제한"이라고 적습니다. 사용자가 첫 번째 턴에서 배송 시간을 묻고, 두 번째 턴에서 "그럼 반품은요?"라고 묻습니다. 두 번째 요청의 messages에는 system, 첫 번째 턴의 user, 첫 번째 턴 모델의 assistant 답변, 두 번째 턴의 user가 순서대로 포함되어야 합니다. 이 중 하나라도 누락되면 모델은 "그"가 무엇을 가리키는지 알 수 없습니다.

샘플링 파라미터: '창의성' 조절

모델이 단어를 생성할 때 모든 후보 단어에 확률 점수를 매긴 후 추첨합니다. 아래 두 파라미터는 이 추첨 규칙을 조정하는 노브입니다.

두 파라미터 모두 '무작위성'을 조절하지만 관점이 다릅니다. 동시에 조정하면 효과를 구분하기 어렵으므로, 한 번에 하나만 변경하는 것을 권장합니다. 이 표준 샘플링 필드는 그대로 전달되며 API는 임의로 수정하지 않습니다.

직관적인 숫자 예시를 들어보겠습니다. 모델이 다음으로 가장 가능성이 높은 세 단어의 확률이 각각 60%, 30%, 10%라고 가정합니다. temperature를 낮추면 60%의 확률이 더 우세해져 매번 첫 번째 단어를 선택하는 것과 같아집니다. 높이면 세 확률이 가까워져 저확률 단어의 선택 가능성이 높아집니다. top_p를 0.9로 설정하면 누적 90%에 도달하는 상위 두 단어만 남고, 세 번째는 제외됩니다. 이 숫자는 원리를 설명하기 위한 가정일 뿐 실제 확률이 아닙니다.

길이 및 종료 제어: max_tokens, stop, stream

max_tokens는 한 번에 제공되는 접시의 크기와 같습니다. 접시가 작으면 음식이 다 제공되기 전에 접시가 치워지며, 이때 finish_reason은 length가 됩니다. stop은 약속된 신호와 같으며, 신호를 받으면 생성을 중단합니다. stream은 내용을 변경하지 않고 전달 방식만 바꿉니다. '모두 완성된 후 제공'에서 '완성된 부분부터 순차적 제공'으로 바뀌어 사용자가 응답이 더 빠르다고 느끼게 합니다.

stop의 실용적인 용도가 있습니다. 모델에게 '질문: ... 답변: ...###'과 같은 고정 형식으로 출력하도록 지시하고, ###을 stop으로 설정하면 구분자에 도달할 때 자동으로 중단됩니다. 이렇게 하면 토큰을 절약하고 불필요한 후속 텍스트를 방지할 수 있습니다. stop이 발동하면 finish_reason 역시 stop이 되므로, 구분하려면 내용을 직접 확인해야 합니다.

tools 및 tool_choice: 모델이 '연락처'를 통해 정보를 요청하게 하기

모델은 실시간 데이터를 직접 조회할 수 없습니다. function calling 방식은 다음과 같습니다: 먼저 모델에 사용 가능한 함수를 알려주고, 모델이 필요하다고 판단하면 직접 답변하지 않고 "어떤 함수를 호출하고, 파라미터는 ..."라고 반환합니다. 당신의 프로그램이 이를 실행한 후 결과를 다시 전달하면, 모델이 이를 바탕으로 답변을 구성합니다. 형식은 OpenAI와 동일합니다.

复制import json
import os
from openai import OpenAI

client = OpenAI(base_url="https://api.apidamoxing.com/v1", api_key=os.environ["API_KEY"])

tools = [{
    "type": "function",
    "function": {
        "name": "get_tide_time",
        "description": "查询某港口今天的高潮时刻",
        "parameters": {
            "type": "object",
            "properties": {"port": {"type": "string", "description": "港口名称"}},
            "required": ["port"],
        },
    },
}]

messages = [{"role": "user", "content": "青岛今天几点涨潮？"}]
first = client.chat.completions.create(
    model="uncensored", messages=messages, tools=tools, tool_choice="auto"
)
msg = first.choices[0].message

if msg.tool_calls:
    call = msg.tool_calls[0]
    args = json.loads(call.function.arguments)
    result = {"port": args["port"], "high_tide": "14:20"}   # 这里换成你自己的查询
    messages.append(msg)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result, ensure_ascii=False)})
    final = client.chat.completions.create(model="uncensored", messages=messages, tools=tools)
    print(final.choices[0].message.content)
else:
    print(msg.content)

프로세스는 두 라운드입니다: 첫 번째 라운드에서 tool_calls를 받고, 두 번째 라운드에서 role이 tool인 결과를 이어붙여 다시 요청합니다. description을 구체적으로 작성할수록 모델이 언제 호출해야 하는지 정확히 파악합니다. 파라미터는 JSON 문자열이므로 반드시 json.loads로 파싱하고 검증하세요. 맹목적으로 신뢰하지 마세요.

응답 필드: 반환된 '영수증' 읽기

성공적인 응답은 대략 다음과 같으며, 필드는 고정되어 있습니다:

复制{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "model": "uncensored",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "因为潮汐锁定……"},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 38, "completion_tokens": 212, "total_tokens": 250}
}

코드에서는 finish_reason을 먼저 확인해야 합니다. length인 경우 사용자에게 내용이 잘렸다고 알리거나 자동으로 이어서 생성합니다. tool_calls인 경우 함수 실행 분기로 이동합니다. usage의 역할은 토큰 및 요금 문서에서 더 자세한 예산 방법을 통해 확인할 수 있습니다.

가장 흔하게 발생하는 파라미터 오해

• max_tokens을 '입력 상한'으로 간주합니다. 이는 출력만 제한하며 입력은 사용자가 제어합니다.
• 모델이 이전 요청의 내용을 기억한다고 생각합니다. 각 요청은 독립적이며, 역사(맥락)는 스스로 가져옵니다.
• temperature를 0으로 설정하면 결과가 항상 완전히 동일하다고 생각합니다. 더 안정적이지만, 문자 그대로의 일치를 가정해서는 안 됩니다.
• 스트리밍 모드에서 choices[0].message를 직접 읽습니다. 스트리밍 청크의 필드는 delta이므로 직접 연결해야 합니다.
• tool 호출 후 tool_calls가 포함된 assistant 메시지를 이어붙이지 않아 두 번째 라운드에서 오류가 발생합니다.

오류 코드 의미 및 재시도 전략은 문서에서 확인할 수 있습니다. 이러한 파라미터를 연결한 완전한 예시를 보려면 채팅 봇 구축 문서를 참조하십시오.