BroadRouter
Начать

Вызов инструментов в открытых моделях: схемы, параллельность, повторы

Команда BroadNet Inference · 4 мин чтения · Опубликовано · Обновлено

Открытые модели в OpenAI-совместимых API используют тот же формат tools и tool_calls, что и OpenAI. Делайте схемы маленькими и плоскими, разбирайте аргументы как JSON-строки, валидируйте их до выполнения и возвращайте ошибки модели как результаты инструментов, чтобы она могла повторить вызов. Ограничьте число шагов. В BroadNet поддержка инструментов указана для GLM 5.3 и Qwen3.8 27B.

Вызов инструментов — то, что превращает модель в агента. С открытыми моделями в OpenAI-совместимом API формат запроса тот же, что и с OpenAI. Различается то, как часто что-то идёт не так, и что сервер делает, чтобы это предотвратить. В статье — формат, как писать схемы, с которыми открытые модели хорошо справляются, параллельные вызовы, пять сбоев, которые вы действительно увидите, и цикл на Python, который их переживает.

Как работает вызов инструментов в OpenAI-совместимом API?

  1. Вы отправляете messages и список tools. У каждого инструмента есть имя, описание и JSON Schema для аргументов.
  2. Модель отвечает с finish_reason: "tool_calls" и списком tool_calls. В каждом элементе есть id, имя функции и arguments в виде JSON-строки.
  3. Ваш код выполняет каждый вызов и добавляет по одному сообщению role: "tool" на вызов с соответствующим tool_call_id.
  4. Вы снова вызываете API. Модель отвечает или запрашивает ещё инструменты.

Сама модель ничего не выполняет. Что запускать, решает ваш код.

Как писать схемы инструментов?

Открытые модели надёжнее следуют простым схемам. Эти правила взяты из руководства OpenAI и из того, что обычно ломается:

  • Называйте инструменты по действию, например read_file или search_code, и пишите в описании, когда использовать каждый.
  • Держите список коротким. Руководство OpenAI называет «меньше 20 функций в начале хода» мягкой рекомендацией. К тому же каждая схема отправляется при каждом вызове; см. бюджет токенов агента.
  • Предпочитайте плоские аргументы. Строки, числа, булевы значения и enum. Избегайте глубокой вложенности и объектов произвольной формы.
  • Используйте enum для фиксированных вариантов, чтобы модель не могла придумать значение. Генератор JSON Schema превращает образец объекта аргументов в плоскую схему, которую можно вставить в parameters.
  • Отмечайте обязательные поля. Строгий режим OpenAI требует additionalProperties: false и все поля в required, а для необязательных — null как один из типов. Обеспечивает ли провайдер strict, бывает по-разному, так что валидируйте в любом случае.

А что с параллельными вызовами?

Модель может вернуть за один ход несколько элементов в tool_calls, например три чтения файлов. Выполняйте независимые вызовы параллельно и возвращайте по одному результату на каждый tool_call_id, в любом порядке. Если у инструментов есть побочные эффекты, зависящие друг от друга, задайте parallel_tool_calls: false; по руководству OpenAI, тогда модель делает не больше одного вызова за ход. Проверьте, что ваш провайдер это учитывает.

Почему вызовы инструментов сбоят?

Сбой Что вы видите Решение
Некорректные аргументы json.loads выбрасывает исключение Вернуть ошибку разбора как результат инструмента; повторить
Несоответствие схеме Нет поля, не тот тип, выдуманное значение enum Валидировать; вернуть ошибку валидации
Неизвестный инструмент Имя, которое вы не определяли Вернуть «unknown tool, available: …»
Нет вызова, когда он нужен Вместо него текстовый ответ tool_choice: "required" или конкретная функция
Обрезанный вызов finish_reason: "length" Увеличить max_tokens; рассуждения делят тот же лимит

Первые два сбоя ожидаемы, а не редки. Документация vLLM по вызову инструментов говорит, что в режиме auto, если инструмент не задаёт strict: true (или сервер не навязывает минимальную строгость) и парсер модели не поддерживает ограничения, “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.” (перевод: «vLLM извлекает вызовы инструментов из сырого текста, поэтому аргументы иногда могут быть некорректными или нарушать схему параметров функции».) Для явно указанной функции vLLM использует бэкенд структурированного вывода. Ваш провайдер может обслуживать модели иначе, поэтому считайте валидацию обязательной.

На последней строке спотыкаются те, кто использует модели с рассуждениями. GLM 5.3 и Qwen3.8 27B размышляют перед ответом, и размышления входят в max_tokens. Почему ответы приходят пустыми или обрезанными — там же сказано, сколько места оставить.

Цикл инструментов с валидацией и повторами

import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up one order by its ID. Use when the user asks where an order is.",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}

def run_call(call):
    name = call.function.name
    if name not in IMPL:
        return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
    try:
        args = json.loads(call.function.arguments or "{}")
        validate(args, SCHEMAS[name])
    except (json.JSONDecodeError, ValidationError) as e:
        return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
    return str(IMPL[name](**args))

def agent(messages, max_steps=8):
    for _ in range(max_steps):
        r = client.chat.completions.create(model=MODEL, messages=messages,
                                           tools=TOOLS, max_tokens=4000)
        msg = r.choices[0].message
        if r.choices[0].finish_reason == "length":
            raise RuntimeError("Output limit reached; raise max_tokens")
        messages.append(msg.model_dump(exclude_none=True))
        if not msg.tool_calls:
            return msg.content
        for call in msg.tool_calls:
            messages.append({"role": "tool", "tool_call_id": call.id,
                             "content": run_call(call)})
    raise RuntimeError("Step limit reached")

Здесь важны три проектных решения:

  1. Ошибки возвращаются модели как результаты инструментов. Модель видит, что было не так, и обычно исправляет это на следующем ходу. Выбросив исключение, вы лишаете её этого шанса.
  2. Цикл ограничен. max_steps останавливает модель, которая продолжает вызывать инструменты без прогресса.
  3. Повторы на уровне транспорта — отдельно. max_retries у клиента обрабатывает 429 и 5xx. Плохие аргументы обрабатываются в цикле. Не смешивайте одно с другим; см. ошибки и повторы.

Для инструментов с побочными эффектами, например отправки письма, добавьте ключ идемпотентности, чтобы повторённый шаг не сработал дважды. Подробнее — в статье о долго работающих агентах.

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

Модель Инструменты указаны Контекст Примечания
GLM 5.3 Да 1 048 576 Также структурированный вывод
Qwen3.8 27B Да 262 144 Также ввод изображений
DeepSeek V4.1 Flash Не указаны 1 048 576 Ввод изображений; протестируйте инструменты, прежде чем на них полагаться
Gemma 4 VL 26B Не указаны 32 768 Не для циклов с инструментами

Как выбрать между двумя моделями с поддержкой инструментов, см. GLM 5.3 или Qwen3.8 27B. Когда итоговый ответ должен иметь определённую форму, но никакую функцию запускать не нужно, структурированный вывод проще инструмента.

Место BroadNet Inference

BroadNet Inference обслуживает GLM 5.3 и Qwen3.8 27B с заявленным вызовом инструментов через стандартный формат chat completions, так что цикл выше работает без изменений с OpenAI Python SDK. Цены за токены — на странице цен. Серверных инструментов вроде веб-поиска или выполнения кода BroadNet не предоставляет, а в документации вызов инструментов не указан для DeepSeek V4.1 Flash — модели безлимитных тарифов. Для агента, активно работающего с инструментами, берите GLM 5.3 или Qwen3.8 27B с оплатой за токены. Если вам всё же нужен фиксированный тариф, перед покупкой месяца проверьте на часе Meteor за $1, что DeepSeek V4.1 Flash надёжно вызывает ваши инструменты.

Вопросы и ответы

Поддерживают ли открытые модели function calling?

Многие поддерживают, но это зависит от модели и от того, как её обслуживает провайдер. В документации BroadNet Inference вызов инструментов указан для GLM 5.3 и Qwen3.8 27B. Для DeepSeek V4.1 Flash и Gemma 4 VL 26B он не указан.

Почему аргументы вызова инструмента — невалидный JSON?

Если сервер не ограничивает декодирование, аргументы генерируются как текст и разбираются уже потом. Документация vLLM говорит, что аргументы, извлечённые из сырого текста, иногда бывают некорректными. Перехватите ошибку разбора и отправьте её обратно как результат инструмента, чтобы модель исправилась.

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

В формате OpenAI задайте parallel_tool_calls равным false. Тогда модель делает не больше одного вызова за ход. Проверьте, что ваш провайдер учитывает это поле.

Почему модель отвечает текстом, а не вызывает инструмент?

При tool_choice auto решает модель. Если вызов обязателен, задайте tool_choice required или конкретную функцию. И проверьте, что в описании инструмента сказано, когда его использовать.

Почему вызов инструмента обрывается?

У моделей с рассуждениями размышления входят в max_tokens. При маленьком лимите ответ может оборваться посреди аргументов. Проверьте finish_reason и увеличьте max_tokens.

Открыть в MarkdownСпросить ChatGPTСпросить ClaudeСпросить Perplexity