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

Извикване на API с инструменти

Урок 5 от 14 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Изпращане на инструменти към Mistral API
  2. Първата заявка
  3. Разбиране на отговора на модела
  4. Парсиране на отговора и извличане на tool_calls
  5. Когато моделът поиска липсваща информация
  6. Обработка на системното съобщение
  7. Пълен код за стъпки 2–3
  8. Ключови изводи

Изпращане на инструменти към Mistral API

Вече дефинирахте своите функции и техните JSON спецификации. Сега трябва да ги изпратите към Mistral API и, което е по-важно, да разберете какво връща моделът. В момента се намираме на стъпки 2 и 3 от процеса: моделът получава потребителската заявка заедно с инструментите и генерира извикване на функция – или отказва да направи такова, което също е поучително.

Първата заявка

import os
import json
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Инструменти, дефинирани в предишния урок
tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Unique transaction identifier (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

# Съобщение от потребителя
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

# API извикване с инструменти
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

Разбиране на отговора на модела

Отговорът съдържа обект message, който може да приеме две форми, и Вашият код трябва да обработва и двете от самото начало. В първия случай моделът отговаря директно, защото не е необходима функция: content съдържа текст, а tool_calls е None.

# response.choices[0].message.content съдържа текстовия отговор
# response.choices[0].message.tool_calls е None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"

Във втория случай моделът иска да извика функция. Ситуацията се обръща: content е празно или null, а tool_calls носи полезния товар.

# response.choices[0].message.content е None или празно
# response.choices[0].message.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}")

Типичен изход:

Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz

Парсиране на отговора и извличане на tool_calls

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

message = response.choices[0].message

if message.tool_calls and len(message.tool_calls) > 0:
    tool_call = message.tool_calls[0]

    # Извличане на името на функцията
    function_name = tool_call.function.name

    # Парсиране на JSON аргументите в Python речник
    function_params = json.loads(tool_call.function.arguments)

    # Извличане на уникалния идентификатор на извикването
    tool_call_id = tool_call.id

    print(f"The model wants to call: {function_name}")
    print(f"With parameters: {function_params}")
    print(f"Call ID: {tool_call_id}")
else:
    # Моделът е отговорил директно
    print(f"Response: {message.content}")

От този блок излизат три части информация, като третата е тази, която хората често забравят. Името на функцията се използва за насочване (dispatching), парсираните аргументи – за самото извикване, но tool_call_id е това, което позволява на модела да свърже Вашия резултат с правилното извикване, когато го изпратите обратно. Ако го загубите, завоят в разговора става невъзстановим.

Когато моделът поиска липсваща информация

Понякога потребителят не предоставя достатъчно информация. Моделът има елегантен изход: изобщо да не извиква функция, а вместо това да зададе уточняващ въпрос.

messages = [
    {"role": "user", "content": "What is the status of my payment?"}
]

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

message = response.choices[0].message
print(message.content)
# → "I need the transaction ID to check the status.
#     Could you please provide the transaction number?"

Това поведение е точно това, което искате. Моделът знае, че transaction_id е посочено в required; вместо да измисли правдоподобен ID и да задейства заявка към несъществуващи данни, той отстъпва думата на потребителя. Това е и най-добрата демонстрация на полезността на полето required, разгледано в предишния урок.

Обработка на системното съобщение

Системното съобщение Ви позволява да рамкирате това поведение, вместо да се надявате на него.

messages = [
    {
        "role": "system",
        "content": "You are a payment tracking assistant. "
                   "Respond in English. "
                   "Use the available tools to answer questions "
                   "about transactions. If the user does not provide "
                   "the transaction ID, ask for it politely."
    },
    {
        "role": "user",
        "content": "What is the status of payment T1001?"
    }
]

Прочетете го ред по ред: първото изречение задава ролята, второто – тона и езика на асистента, третото уточнява кога да се използват функции, а последното дава изрична инструкция за граничен случай – липсваща информация. Това са трите случая на употреба, за които се препоръчва системно съобщение, и те са достатъчни в повечето случаи.

Пълен код за стъпки 2–3

Ето пълния, многократно използваем код за изпращане на заявка с инструменти. Той обединява всичко казано дотук и нормализира отговора в речник с две форми, спестявайки Ви разпръскването на проверки if message.tool_calls из цялото Ви приложение.

import os
import json
from mistralai.client import Mistral

def call_mistral_with_tools(
    messages: list,
    tools: list,
    model: str = "mistral-large-latest",
    tool_choice: str = "auto"
) -> dict:
    """Sends a request to Mistral with tools and returns the parsed response."""
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

    response = client.chat.complete(
        model=model,
        messages=messages,
        tools=tools,
        tool_choice=tool_choice
    )

    message = response.choices[0].message

    if message.tool_calls and len(message.tool_calls) > 0:
        return {
            "type": "tool_call",
            "message": message,
            "tool_calls": [
                {
                    "id": tc.id,
                    "function_name": tc.function.name,
                    "arguments": json.loads(tc.function.arguments)
                }
                for tc in message.tool_calls
            ]
        }

    return {
        "type": "text",
        "message": message,
        "content": message.content
    }

Обърнете внимание, че списъчното включване (list comprehension) итерира през всички tool_calls, а не само през първото. Моделът може да генерира няколко едновременно; по-късен урок ще разгледа това, но Вашата спомагателна функция вече е готова да ги обработи.

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

  • Изпратете tools и messages към client.chat.complete(), за да активирате извикването на функции
  • Винаги проверявайте дали message.tool_calls съществува, преди да опитате да парсирате
  • tool_call_id е задължителен за изпращане на резултата обратно към модела
  • Аргументите са JSON низ, който трябва да се парсира с json.loads()
  • Моделът може да избере да отговори директно, ако не му е необходима функция или ако липсва информация