Премини към основното съдържание
Български— Изберете език
Меню

Дефиниране на инструменти в JSON

Урок 4 от 14 Обновен 29 юли 2026 г. Програмист
На тази страница
  1. От теория към практика
  2. Структура на заявката с инструменти
  3. Ключови фигури за реализацията
  4. Обработка на отговора tool_call
  5. Изпълнение и връщане на резултата
  6. Дефиниране на множество инструменти
  7. Проверка на finish_reason
  8. Ключови изводи

От теория към практика

Сега разбирате концепцията за извикване на функции и структурата на JSON схемите. Време е да преминете към конкретна реализация. В този урок ще научите как да изградите пълна заявка с дефиниции на инструменти и как да обработите отговора на модела.

Структура на заявката с инструменти

Ето пълна заявка към Grok API с дефиниран инструмент:

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.x.ai/v1"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "default": "celsius"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="grok-4.5",
    messages=[
        {"role": "user", "content": "What's the weather like in Paris?"}
    ],
    tools=tools
)

Обърнете внимание на вложената структура: обектът tools съдържа масив, където всеки елемент има поле type и обект function с детайлите.

Ключови фигури за реализацията

200
Максимален брой инструменти на заявка
6
Поддържани JSON типове
3
Съвместими SDK
1
Заявка = целият поток

Обработка на отговора tool_call

Когато моделът реши да извика функция, отговорът съдържа масив tool_calls:

message = response.choices[0].message

if message.tool_calls:
    for tool_call in message.tool_calls:
        print(f"Function: {tool_call.function.name}")
        print(f"Arguments: {tool_call.function.arguments}")
        print(f"ID: {tool_call.id}")

Полето tool_call.function.arguments е JSON низ (не Python обект). Трябва да го анализирате:

import json

args = json.loads(tool_call.function.arguments)
city = args["city"]
unit = args.get("unit", "celsius")

Изпълнение и връщане на резултата

След изпълнението на функцията, изпращате резултата обратно към модела във второ извикване:

import json

# 1. Изпълнете функцията
weather_data = get_weather(city="Paris", unit="celsius")

# 2. Изградете съобщенията с резултата
messages = [
    {"role": "user", "content": "What's the weather like in Paris?"},
    message,  # Отговорът на модела с tool_calls
    {
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(weather_data)
    }
]

# 3. Извикайте модела отново с резултата
final_response = client.chat.completions.create(
    model="grok-4.5",
    messages=messages,
    tools=tools
)

print(final_response.choices[0].message.content)

Съобщението с роля tool трябва да съдържа:

  • tool_call_id: уникалният идентификатор на tool_call (за свързване със заявката)
  • content: резултатът като JSON низ

Дефиниране на множество инструменти

Можете да декларирате толкова инструменти, колкото е необходимо, в масива tools:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": { ... }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_restaurants",
            "description": "Search for restaurants by city and cuisine type",
            "parameters": { ... }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "book_table",
            "description": "Book a table at a restaurant",
            "parameters": { ... }
        }
    }
]

Моделът автоматично ще избере подходящия инструмент (или инструменти) въз основа на потребителската заявка.

Проверка на finish_reason

Полето finish_reason в отговора показва дали моделът е завършил отговора си или очаква резултат от инструмент:

finish_reason = response.choices[0].finish_reason

if finish_reason == "tool_calls":
    # Моделът очаква резултат от един или повече инструменти
    handle_tool_calls(response)
elif finish_reason == "stop":
    # Моделът е завършил своя отговор
    print(response.choices[0].message.content)

Ключови изводи

  • Заявката съдържа messages и tools (дефиниции)
  • Аргументите на tool_call са JSON низ, който трябва да се анализира
  • Изпратете резултата в съобщение с роля tool, включващо tool_call_id
  • Проверете finish_reason, за да разберете дали моделът очаква резултат
  • Можете да декларирате множество инструменти – моделът избира автоматично