Подробно о параметрах API больших языковых моделей: от полей запроса до полей ответа

Как выглядит запрос

Адрес эндпоинта: POST https://api.apidamoxing.com/v1/chat/completions. Заголовок авторизации: Authorization: Bearer <key>. Тело запроса — JSON, совместимый с API чат-дополнения OpenAI. Ниже полный пример запроса с использованием всех полей:

复制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 указано «Отвечайте только на вопросы по заказам, не более трёх предложений». Пользователь в первом запросе спрашивает о доставке, а во втором уточняет: «А как насчёт возврата?». Во втором запросе 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: вызов функций моделью

Модель не имеет доступа к данным в реальном времени. При вызове функций вы сначала указываете доступные функции. Если модель решает, что они нужны, она не отвечает напрямую, а возвращает запрос на вызов функции с параметрами. Ваша программа выполняет функцию и возвращает результат, после чего модель формирует ответ. Формат данных совместим с 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 и отправляете запрос снова. Чем конкретнее описание, тем лучше модель понимает, когда вызывать функцию. Параметры — это строка JSON; обязательно используйте json.loads для разбора и проверки, не доверяйте данным наугад.

Поля ответа: как читать «чек» от API

Успешный ответ обычно имеет следующую структуру, поля фиксированы:

复制{
  "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, его нужно склеивать самостоятельно.
• После вызова функции забывают добавить сообщение от assistant с tool_calls, что приводит к ошибке на втором шаге.

Значения кодов ошибок и стратегии повторных попыток описаны в документации. Полный пример использования всех параметров см. в статье Создание чат-бота.