Практическое руководство по Kimi K3: новые параметры и матрица поддержки API

В этой статье рассматриваются новые параметры и примечания по использованию Kimi K3. На AIHubMix K3 доступен через API Chat Completions, Responses и Claude-compatible Messages. Также см.: официальная документация платформы Moonshot.

«Подтвержденные» выводы и примеры ответов в каждом разделе получены из фактических вызовов, сделанных 2026-07-17 через API AIHubMix (Chat Completions / Responses / Messages).

1. Характеристики модели на первый взгляд

Подтверждено: оба ограничения stop проверены, и превышение любого из них возвращает 400; API Messages применяет ту же проверку к stop_sequences.

❗ Когда достигается последовательность остановки, API Messages не следует семантике Anthropic: в тестировании stop_reason равен "end_turn" (вместо "stop_sequence"), stop_sequence равен null, и видимый текст перед словом остановки может быть пустым. Клиенты, которые полагаются на эти два поля для обнаружения усечения, должны это учитывать.

# остановка с 6 записями / записью длиной 33 байта -> HTTP 400
"Неверный запрос: массив остановки слишком длинный. Ожидался массив максимальной длины 5, но получен массив длиной 6"
"Неверный запрос: последовательность остановки не должна превышать 32, но получена 33"

2. Режим мышления: reasoning_effort поддерживает только max

Мышление K3 включено по умолчанию, и reasoning_effort поддерживает только один уровень: "max".

Многоходовые разговоры должны передавать историю мышления дословно: согласно официальной документации Moonshot, K3 обучен с сохранением мышления, поэтому в многоходовых разговорах предыдущее сообщение помощника должно быть передано полностью и без изменений (включая содержание мышления). Отсутствие истории мышления приводит к нестабильному качеству вывода. Если вы используете фреймворк управления сессиями или прокси-слой, подтвердите, что содержание мышления передается без обрезки.
Chat Completions

Содержание мышления возвращается в поле reasoning_content ответа; в многоходовых разговорах передавайте предыдущее сообщение помощника (включая reasoning_content) дословно.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

completion = client.chat.completions.create(
    model="kimi-k3",
    reasoning_effort="max",
    messages=[
        {"role": "user", "content": "У улитки есть 10-метровый колодец. Каждый день она поднимается на 3 метра, но каждую ночь скользит назад на 2 метра. Сколько дней ей потребуется, чтобы добраться до верха?"}
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)

# Многоходовой: передайте предыдущее сообщение помощника дословно
messages = [
    {"role": "user", "content": "Какова столица Франции?"},
    {"role": "assistant", "content": "Париж.", "reasoning_content": "<reasoning_content from the previous response>"},
    {"role": "user", "content": "А его население?"},
]

Подтверждено: ответ возвращает reasoning_content; после передачи предыдущего сообщения помощника (включая reasoning_content) дословно, последующие ходы отвечают нормально.
Ответы

Содержание мышления возвращается как элемент вывода reasoning; в многоходовых разговорах добавьте элементы вывода предыдущего хода (reasoning + message) обратно в input дословно.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

response = client.responses.create(
    model="kimi-k3",
    input="Ответьте одним словом: столица Франции",
)

# Наблюдаемые типы элементов response.output: ["reasoning", "message"]; текст: "Париж"
# Многоходовой: input = [первое сообщение пользователя] + response.output + [следующее сообщение пользователя]
# Наблюдаемый ответ второго хода с переданными элементами вывода: "Берлин"

Сообщения

Содержание мышления возвращается как родные блоки thinking; в многоходовых разговорах передавайте предыдущие блоки содержимого помощника (включая блоки мышления) обратно дословно.

from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com"
)

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Ответьте одним словом: столица Франции"}
    ],
)

# Наблюдаемые типы блоков response.content: ["thinking", "text"]; текст: "Париж"
# Многоходовой: передайте response.content обратно дословно как сообщение помощника

3. Параметры выборки фиксированы

Параметры выборки K3 фиксированы поставщиком модели: temperature 1.0, top_p 0.95, n 1 и presence_penalty / frequency_penalty 0. Официальная рекомендация — не указывать эти параметры в запросах.

Примечание: фиксированные значения выборки являются частью официальной спецификации и не могут быть проверены по сигналам ответа; следуйте официальной рекомендации и не указывайте эти параметры.

4. Вызов инструментов и динамическая загрузка инструментов

tools поддерживает до 128 инструментов; tool_choice поддерживает принудительные и отключенные вызовы инструментов. K3 также поддерживает динамическую загрузку инструментов: внедрение новых инструментов в процессе разговора через поле tools системного сообщения (форма сообщения, специфичная для Chat API).
Chat Completions

tool_choice поддерживает auto / none / required; required принуждает модель вызывать инструмент. Динамическая загрузка инструментов: системное сообщение, внедряющее инструмент, не содержит content, внедренные инструменты вступают в силу для последующих ходов, и сообщение должно быть включено снова в каждый запрос.

messages = [
    {"role": "system", "content": "Вы полезный помощник."},
    {"role": "user", "content": "Здравствуйте."},
    {"role": "assistant", "content": "Здравствуйте, чем я могу вам помочь?"},
    # Внедрить новый инструмент в процессе разговора: только поле tools, без содержимого
    {
        "role": "system",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_time",
                    "description": "Получить текущее время",
                    "parameters": {"type": "object", "properties": {}},
                },
            }
        ],
    },
    {"role": "user", "content": "Сколько сейчас времени?"},
]

# tool_choice="required" с подсказкой "Здравствуйте" -> модель принуждена вызвать инструмент
"finish_reason": "tool_calls",
"tool_calls": [{"function": {"name": "get_weather", "arguments": "{\"city\":\"New York\"}"}}]

Подтверждено: tool_choice: "required" принуждает вызов инструмента даже для несвязанных подсказок; "none" подавляет вызовы инструментов; инструменты, внедренные в процессе разговора через системное сообщение без content, могут вызываться нормально.
Ответы

Определения инструментов используют плоскую структуру (name на верхнем уровне); принудительный вызов также использует tool_choice: "required", и вызовы возвращаются как элементы вывода function_call. Поддержка динамической загрузки инструментов в процессе разработки; на данный момент объявите все инструменты в верхнем уровне параметра tools.

response = client.responses.create(
    model="kimi-k3",
    input="Здравствуйте",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Получить погоду для города",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice="required",
)

# Наблюдаемый вывод содержит: {"type": "function_call", "name": "get_weather", "arguments": "{\"city\":\"London\"}"}

Сообщения

Инструменты используют формат Anthropic (input_schema); принудите вызов с tool_choice: {"type": "any"} и отключите вызовы с {"type": "none"}. ❗ Официальная конечная точка сообщений Kimi K3 (совместимая с Anthropic) не поддерживает динамическую загрузку инструментов: в тестировании внедряющее сообщение возвращает 200, но внедренный инструмент не имеет эффекта (модель не может его вызвать). Объявите все инструменты в верхнем уровне параметра tools.

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    tools=[{
        "name": "get_weather",
        "description": "Получить погоду для города",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    tool_choice={"type": "any"},
    messages=[{"role": "user", "content": "Здравствуйте"}],
)

# Наблюдаемый: stop_reason "tool_use"; содержимое содержит блок tool_use, вызывающий get_weather

5. Структурированный вывод

Структурированный вывод заставляет модель возвращать содержимое, строго соответствующее заданной JSON-схеме.
Chat Completions

response_format поддерживает json_schema с strict режимом.

completion = client.chat.completions.create(
    model="kimi-k3",
    messages=[
        {"role": "user", "content": "Париж — столица Франции. Извлеките название города."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "extract",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"city": {"type": "string"}},
                "required": ["city"],
            },
        },
    },
)

# Наблюдаемый ответ: {"city":"Париж"}

Подтверждено: вывод является действительным JSON, соответствующим схеме.
Ответы

Структурированный вывод объявляется через text.format.

response = client.responses.create(
    model="kimi-k3",
    input="Париж — столица Франции. Извлеките название города.",
    text={
        "format": {
            "type": "json_schema",
            "name": "extract",
            "strict": True,
            "schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        }
    },
)

# Наблюдаемый вывод текста: {"city":"Париж"}

Сообщения

❗ Официальная конечная точка сообщений Kimi K3 (совместимая с Anthropic) не поддерживает структурированный вывод: поля структурированного вывода игнорируются без предупреждений: запрос возвращает HTTP 200 с текстом произвольного формата, без ошибок или уведомлений о запасном варианте, и последующий анализ JSON потерпит неудачу. Когда вам нужен структурированный вывод, используйте API Chat Completions или Responses.

6. Кэширование контекста происходит автоматически

Кэширование контекста K3 включено автоматически, без необходимости в параметрах. Когда повторяющийся длинный префикс попадает в кэш, количество попаданий сообщается в использовании (имя поля варьируется в зависимости от API). Цены на кэширование указаны на странице модели.
Chat Completions

# использование второго вызова с идентичным длинным префиксом
"prompt_tokens_details": {"cached_tokens": 1536}

Подтверждено: второй запрос с идентичным длинным префиксом сообщает о попадании в usage.prompt_tokens_details.cached_tokens.
Ответы

# использование второго вызова Responses с идентичными длинными инструкциями
"input_tokens_details": {"cached_tokens": 1536}

Сообщения

# использование второго вызова Messages с идентичным длинным системным запросом
"cache_read_input_tokens": 1536

7. Завершение частичного префикса partial

Завершение префикса заставляет модель продолжать генерировать из данного префикса, что хорошо подходит для завершения кода и вывода с контролируемым форматом.
Chat Completions

Передайте "partial": true в последнем сообщении помощника.

messages = [
    {"role": "user", "content": "Напишите хайку о море."},
    {"role": "assistant", "content": "Волны складываются в пену,", "partial": True},
]

# Префикс: "Волны складываются в пену," -> продолжение, возвращенное моделью
# соль висит в воздухе—
# луна тянет прилив домой.

Подтверждено: генерация продолжается с данного префикса без его повторения.
Ответы

Передайте префикс как сообщение помощника в конце массива input; параметр partial не нужен.

response = client.responses.create(
    model="kimi-k3",
    input=[
        {"role": "user", "content": "Напишите хайку о море."},
        {"role": "assistant", "content": "Волны складываются в пену,"},
    ],
)

# Наблюдаемое продолжение: "соль висит в воздухе— / луна тянет прилив домой."

Сообщения

Та же возможность достигается с помощью родного предзаполнения помощника протокола, без параметра partial: передайте префикс как последнее сообщение помощника.

response = client.messages.create(
    model="kimi-k3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Напишите хайку о море."},
        {"role": "assistant", "content": "Волны складываются в пену,"},
    ],
)

# Наблюдаемое продолжение: "соль тянет криком чаек— / прилив тянет ..."

8. Входные данные для визуализации

Изображения передаются в формате base64; формат блока содержимого варьируется в зависимости от API.
Chat Completions

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Какой доминирующий цвет на этом изображении? Одно слово."},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,<BASE64>"}},
        ],
    }
]

# Наблюдаемое содержимое ответа: "Красный"  (ввод: 64x64 сплошной красный PNG)

Подтверждено: ввод изображения в формате base64 работает, и модель правильно описывает тестовое изображение.
Ответы

input = [
    {
        "role": "user",
        "content": [
            {"type": "input_text", "text": "Какой доминирующий цвет на этом изображении? Одно слово."},
            {"type": "input_image", "image_url": "data:image/png;base64,<BASE64>"},
        ],
    }
]

# Наблюдаемый текст вывода: "Красный"

Сообщения

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Какой доминирующий цвет на этом изображении? Одно слово."},
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "<BASE64>"}},
        ],
    }
]

# Наблюдаемый текст ответа: "Красный"

9. Подтвержденная ссылка: задержка и использование длительной задачи одного вызова

Мышление K3 фиксировано на максимальном уровне, поэтому одиночные запросы на сложные задачи занимают значительно больше времени, чем на типичных моделях. Измеренные данные из задачи генерации HTML-игры в одном файле (одна подсказка с эталонным изображением, сгенерированная за один раз без итераций): одиночный запрос занял 2,541 секунды (примерно 42 минуты), с 74,994 токенами завершения, из которых 54,486 (73%) были токенами мышления; окончательный вывод составил 1,275 строк непосредственно исполняемого кода, с finish_reason stop.

Рекомендации для клиентов:

• Установите тайм-ауты клиента на минуты или дольше и предпочитайте потоковую передачу для длительных задач;
• Оставьте достаточно места в max_completion_tokens: в этом случае только мышление потребило 54,486 токенов.

10. Матрица возможностей × поддержки API

Каждая ячейка в таблице ниже была проверена 2026-07-17 через фактические вызовы к производственным API AIHubMix; каждая ячейка показывает синтаксис параметра / поля для соответствующего API.

Часто задаваемые вопросы

Какие API поддерживает K3 на AIHubMix?
Chat Completions (/v1/chat/completions), Responses (/v1/responses) и API сообщений, совместимый с Claude (/v1/messages).

Можно ли отключить или уменьшить мышление?
Нет. Мышление K3 включено по умолчанию, и reasoning_effort поддерживает только один уровень "max".

Почему reasoning_content должно передаваться обратно в многоходовых разговорах?
K3 обучен с сохранением мышления; Moonshot требует, чтобы предыдущее сообщение помощника передавалось полностью и без изменений. Отсутствие истории мышления приводит к нестабильному качеству вывода.

Каковы ограничения на параметр stop?
Максимум 5 последовательностей остановки, каждая не длиннее 32 байт; превышение любого из ограничений возвращает ошибку 400.

Поддерживает ли API сообщений структурированный вывод?
❗ Нет. Официальная конечная точка сообщений Kimi K3 (совместимая с Anthropic) без предупреждений игнорирует поля структурированного вывода (возвращая 200 с текстом произвольного формата и без ошибок). Для структурированного вывода используйте response_format на Chat Completions или text.format на Responses.

Почему одиночные запросы K3 занимают так много времени?
Мышление K3 фиксировано на максимальном уровне, и токены мышления составляют большую долю при сложных задачах (73% токенов завершения в измеренном случае). Установите тайм-ауты клиента на минуты или дольше и используйте потоковую передачу.

Для цен и статуса в реальном времени смотрите страницу модели Kimi K3; для получения дополнительных моделей посетите галерею моделей.

Последнее обновление: 2026-07-17