Mistral Responses API: настройка Large 4 и переход с OpenAI

Вызывайте Mistral Responses API с mistral-large-4 и передавайте историю диалога в input при каждом запросе. Уберите параметры серверного продолжения, оставьте store выключенным и выберите поддерживаемое моделью значение reasoning.effort. По состоянию на 2026-11-01 Responses API Mistral доступен в открытом тестировании — public preview.

Первый запрос к Mistral Large 4

Начните с актуального Python SDK Mistral и API-ключа Mistral. Сначала проверьте этот документированный пример, затем адаптируйте существующий клиент Responses.

Понадобится Python 3.10 или новее. Создайте ключ в разделе Studio → API keys и выполните команды в Bash. После запуска read вставьте ключ и нажмите Enter: ввод не отображается на экране.

python3 -m pip install -U mistralai
read -rs MISTRAL_API_KEY && export MISTRAL_API_KEY

Сохраните следующий код в mistral_responses.py. Функция create_response задаёт общие инструкции и настройки для последующих примеров.

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
MODEL = "mistral-large-4"
INSTRUCTIONS = "Answer concisely."

def create_response(history, **options):
    result = client.responses.create(
        model=MODEL,
        input=history,
        instructions=INSTRUCTIONS,
        reasoning={"effort": "high"},
        max_output_tokens=4096,
        additional_properties={
            "store": False,
            "background": False,
            "truncation": "disabled",
        },
        **options,
    )
    if result.status != "completed":
        raise RuntimeError(
            f"{result.status}: {result.error or result.incomplete_details}"
        )
    return result

def answer_text(result):
    return "".join(
        part.text
        for item in result.output if item.type == "message"
        for part in item.content if part.type == "output_text"
    )

history = [{"role": "user", "content": "Explain a stateless API in one sentence."}]
response = create_response(history)
print(response.status)
print(answer_text(response))

Запустите файл в той же сессии Bash:

python3 mistral_responses.py

В этом примере признак успеха — строка completed и непустое пояснение после неё. Точная формулировка ответа может отличаться. Функция answer_text выбирает текст ответа, поскольку output также может содержать рассуждения и вызовы функций.

Адрес HTTP-запроса: https://api.mistral.ai/v1/responses. Для прямого HTTP-запроса используйте заголовок Authorization: Bearer $MISTRAL_API_KEY. Если клиент сам добавляет /responses, укажите базовый адрес (Base URL) https://api.mistral.ai/v1.

Остальные примеры на Python используют переменные и функции из этого файла. Добавляйте нужные фрагменты в его конец. Каждый повторный запуск выполнит все включённые вызовы генерации.

Какие параметры изменить при переходе с OpenAI Responses?

Прежде чем отправлять существующий запрос OpenAI Responses в Mistral, проверьте его поля JSON по таблице. В справочнике Responses API перечислены следующие требования по состоянию на 2026-11-01.

Параметр запроса	Требование Mistral	Что изменить
`previous_response_id`	Не передавать или задать `null`.	Передавайте предыдущие элементы ответа в `input`.
`conversation`	Не передавать или задать `null`.	Храните историю диалога в приложении.
`store`	Не передавать либо задать `false` или `null`.	Уберите `true`; не рассчитывайте на сохранённые ответы.
`background`	Только `false`; это значение по умолчанию.	Уберите фоновую генерацию и опрос её состояния.
`truncation`	Только `"disabled"`; это значение по умолчанию.	Проверяйте размер контекста до отправки запроса.
`prompt`	Не передавать или задать `null`.	Перенесите текст запроса в `input` и `instructions`.
`moderation`	Не передавать или задать `null`.	Уберите передаваемое значение этого поля.
`top_logprobs`	Не передавать либо задать `0` или `null`.	Уберите положительное значение.
`max_tool_calls`	Принимается, но пока игнорируется.	Ограничивайте число выполнений функций в приложении.
`reasoning.effort`	Значение должна поддерживать выбранная модель.	Используйте значения из таблицы моделей ниже.
`tools`	Функции, которые выполняет приложение; их можно объединять в пространства имён.	Замените зависимости от инструментов, которые выполняет провайдер.
`max_output_tokens`	Общий бюджет токенов для рассуждений и текста ответа.	Оставьте достаточно токенов для обеих частей.

Именованные аргументы Python SDK не повторяют весь набор полей HTTP-запроса. В текущей реализации Responses поля store, background и truncation передают через additional_properties. Первый пример использует именно этот способ.

Учитывайте эти различия в конфигурации провайдера. Замена адреса API сама по себе не подтверждает совместимость инструментов, продолжения диалога и обработки потока. В руководстве по совместимости Messages, Chat Completions и Responses разобрано, зачем проверять полный цикл вызова функции.

Какие модели и возможности доступны?

Для этих примеров используйте mistral-large-4, а при смене модели заново проверьте её возможности. В официальном анонсе Mistral заявляет поддержку всех размещённых у компании чат-моделей, включая Large 4.

В списке поддерживаемых возможностей указаны ввод и вывод текста, структурированный вывод, потоковая передача, вызовы функций и рассуждения с учётом возможностей модели. Изображения можно передавать по URL или через base64 data URL; для этого нужна модель с поддержкой изображений. Для файлов доступны HTTPS URL, base64 data URL и идентификаторы загруженных файлов; поддержка зависит от модели.

Структурированный вывод задаётся через text.format: доступны режим JSON и JSON Schema. Функции выполняет ваше приложение. Текущая реализация поддерживает только такие функции, поэтому инструмент web_search, который выполняет провайдер, нельзя перенести в запрос без изменений.

Уровень рассуждений в Responses задаётся вложенным полем reasoning.effort. Значения ниже соответствуют руководству Mistral по рассуждениям, проверенному 2026-11-01.

Модель	Допустимые значения	Как выбрать
`mistral-large-4` / `mistral-large-4-0`	`low`, `medium`, `high`	Для примера начните с `high`. Сравните меньшие значения, если важны задержка или расход токенов.
`mistral-small-2603`	`none`, `high`	Выберите `high`, если нужен режим рассуждений.
`mistral-medium-3-5`	`none`, `high`	Для существующих интеграций. Модель помечена как устаревшая (deprecated).

Large 4 не принимает none, minimal, xhigh и max. Если вы использовали ранние примеры Large 4 Preview, замените none на low. Наличие значения в общем перечислении SDK не означает, что его поддерживает выбранная модель.

В карточке Large 4 также указан статус public preview. В карточке Medium 3.5 датой перехода в статус deprecated указано 2026-10-31. Для новых интеграций Mistral рекомендует Large 4.

Как передавать историю диалога и результаты функций

Храните полную последовательность элементов диалога, включая рассуждения и вызовы функций. Текст для показа пользователю не заменяет полную историю.

Продолжение диалога

Сначала добавьте в историю все элементы предыдущего output, затем новое сообщение пользователя. Поместите этот фрагмент после первого примера:

history.extend(response.output)
history.append({"role": "user", "content": "What must the client send next time?"})
response = create_response(history)
print(answer_text(response))
history.extend(response.output)

Во втором запросе будут первое сообщение пользователя, весь первый ответ и уточняющий вопрос. Функция create_response также повторно передаст instructions.

Так приложение продолжает диалог вместо передачи previous_response_id. Этот API не восстанавливает историю по одному идентификатору ответа. Если сохранять только отображаемый текст, остальные элементы ответа будут потеряны.

Возврат результата функции

Выполните функцию локально и верните результат с соответствующим call_id. В примере Mistral с вызовом функций поля type, name, description и parameters расположены на одном уровне объекта инструмента. Следующий пример использует эту структуру для сложения двух целых чисел и хранит историю отдельно от предыдущего диалога.

import json

TOOLS = [{
    "type": "function",
    "name": "add",
    "description": "Add two integers.",
    "parameters": {
        "type": "object",
        "properties": {
            "a": {"type": "integer"},
            "b": {"type": "integer"},
        },
        "required": ["a", "b"],
        "additionalProperties": False,
    },
}]
tool_history = [{"role": "user", "content": "Use add to calculate 19 + 23."}]
response = create_response(
    tool_history,
    tools=TOOLS,
    tool_choice={"type": "function", "name": "add"},
    parallel_tool_calls=False,
)
tool_history.extend(response.output)

calls = [item for item in response.output if item.type == "function_call"]
if len(calls) != 1 or calls[0].name != "add":
    raise RuntimeError("Expected exactly one add call.")

call = calls[0]
args = json.loads(call.arguments)
if (
    not isinstance(args, dict)
    or set(args) != {"a", "b"}
    or any(type(args[name]) is not int for name in ("a", "b"))
):
    raise ValueError("Expected two integer arguments.")

result = args["a"] + args["b"]
print("Local result:", result)
tool_history.append({
    "type": "function_call_output",
    "call_id": call.call_id,
    "output": json.dumps({"result": result}),
})
response = create_response(
    tool_history,
    tools=TOOLS,
    tool_choice="none",
    parallel_tool_calls=False,
)
print(answer_text(response))
tool_history.extend(response.output)

Проверьте, что вывод содержит Local result: 42, а следующий ответ использует полученное значение. Формулировка ответа модели может отличаться.

Первый запрос принудительно выбирает add. Во втором значение "none" запрещает новые вызовы, как указано в справочнике API. Пример ограничен двумя запросами генерации и одним локальным выполнением функции.

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

Сохраните все элементы полученного output до добавления результатов функций. Связывайте результат по call_id, а не по полю id элемента ответа. Если разрешены несколько вызовов, проверьте каждый и передайте все результаты до следующего запроса к модели.

Как подсчитать входные токены перед следующим запросом

Считайте токены для всего следующего запроса: истории, инструкций и описаний инструментов. Подсчёт только нового сообщения пропустит данные, которые приложение отправляет повторно.

После примера с функцией добавьте:

next_input = tool_history + [
    {"role": "user", "content": "Explain that calculation in one sentence."}
]
count = client.responses.count_input_tokens(
    model=MODEL,
    input=next_input,
    instructions=INSTRUCTIONS,
    tools=TOOLS,
    reasoning={"effort": "high"},
    parallel_tool_calls=False,
    tool_choice="auto",
)
print(count.input_tokens)

Этот код вызывает POST /v1/responses/input_tokens и печатает input_tokens. Подсчёт не генерирует ответ модели. При последующей генерации используйте ту же модель и те же значения input, instructions и tools.

Сравните число токенов с размером контекстного окна модели и оставьте запас для вывода. Поскольку truncation должен оставаться "disabled", приложение само решает, когда сокращать историю.

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

Число токенов само по себе не даёт стоимость запроса. Для оценки затрат на повторные запросы и влияния кеширования смотрите актуальные тарифы Mistral API.

Как найти причину ошибки при миграции

Начните с конфигурации запроса, затем проверьте статус и элементы ответа. Выберите проверку, которая соответствует симптому.

SDK отклоняет аргумент до отправки запроса. Проверьте установленную версию SDK и сигнатуру метода. В используемой здесь реализации передавайте store, background и truncation внутри additional_properties.
API отклоняет запрос. Вернитесь к первому текстовому примеру. Проверьте идентификатор модели, допустимый уровень рассуждений и таблицу параметров. После успешного запроса возвращайте дополнительные поля по одному.
Модель теряет предыдущий контекст. Проверьте следующий массив input. Он должен содержать предыдущие сообщения и полные элементы ответов, а не только идентификатор ответа.
В ответе нет текста. Проверьте status, error и incomplete_details. Посмотрите, нет ли вызова функции, который ожидает выполнения. Если генерация исчерпала бюджет вывода, увеличьте его или уменьшите уровень рассуждений в пределах допустимых для модели значений.
Запрос уходит по неверному пути. Сравните итоговый URL с https://api.mistral.ai/v1/responses. В руководстве по Base URL и ошибкам адреса API разобраны распространённые ошибки построения пути.

Для потоковой передачи задайте stream=True и обрабатывайте события Responses. В официальном примере на Python каждое событие читается через frame.data. Текст приходит в response.output_text.delta, а завершение обозначает событие response.completed.

Обрабатывайте также события response.failed, response.incomplete и error. Получение части текста ещё не подтверждает успешное завершение запроса. Фоновая генерация отключена, поэтому отдельный цикл опроса состояния здесь не нужен.

Когда выбрать Responses, Chat Completions или Conversations

Выбирайте Responses, если приложению подходит формат отдельных элементов ответа и оно само хранит историю и выполняет функции.

Что нужно приложению	С чего начать	Почему
Элементы ввода и вывода Responses, а также потоковые события Responses	Responses API	Сохраняется нужный формат; историей и выполнением функций управляет приложение.
Продолжить работу существующей интеграции на основе сообщений	Chat Completions	Можно сохранить обработку запросов и ответов в формате сообщений.
Продолжать сохранённые диалоги или использовать инструменты, которые выполняет Mistral	Conversations API	Есть идентификаторы диалогов и отдельный интерфейс серверных инструментов.

В руководстве по Chat Completions описан формат на основе сообщений. Справочник Conversations описывает продолжение диалога через conversation_id.

Для поиска на стороне Mistral инструменты web_search и web_search_premium описаны в разделе Conversations и Agents. Это отдельная возможность, которая не входит в клиентские функции Responses.

Если приложение зависит от сохранённого на сервере диалога или серверных инструментов, оцените Conversations до переноса запросов. Если приложение уже хранит историю и выполняет функции, проверьте текстовый запрос, следующий ход диалога и полный цикл вызова функции. Затем подключайте весь агент.