Przejdź do głównej treści
Polski— Wybierz język
Menu

Wywołaj API za pomocą narzędzi

Lekcja 5 z 14 Zaktualizowano 2 listopada 2026 Programista
Na tej stronie
  1. Wyślij narzędzia do API Mistral
  2. Pierwsze żądanie
  3. Zrozumienie odpowiedzi modelu
  4. Parsowanie odpowiedzi i ekstrakcja tool_calls
  5. Gdy model żąda brakujących informacji
  6. Obsługa wiadomości systemowej
  7. Kompletny kod dla kroków 2–3
  8. Kluczowe wnioski

Wyślij narzędzia do API Mistral

Zdefiniowałeś już swoje funkcje i ich specyfikacje JSON. Teraz musisz wysłać je do API Mistral i, co ważniejsze, zrozumieć, co zwraca model. Jesteśmy obecnie na krokach 2 i 3 procesu: model otrzymuje żądanie użytkownika wraz z narzędziami i generuje wywołanie funkcji – lub odmawia jego wykonania, co również jest pouczające.

Pierwsze żądanie

import os
import json
from mistralai.client import Mistral

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

# Narzędzia zdefiniowane w poprzedniej lekcji
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"]
            }
        }
    }
]

# Wiadomość użytkownika
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

# Wywołanie API z narzędziami
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

Zrozumienie odpowiedzi modelu

Odpowiedź zawiera obiekt message, który może przybrać dwie formy i Twój kod musi obsługiwać obie od samego początku. W pierwszym przypadku model odpowiada bezpośrednio, ponieważ żadna funkcja nie jest potrzebna: content zawiera tekst, a tool_calls ma wartość None.

# response.choices[0].message.content zawiera odpowiedź tekstową
# response.choices[0].message.tool_calls ma wartość None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"

W drugim przypadku model chce wywołać funkcję. Sytuacja jest odwrotna: content jest puste lub null, a tool_calls zawiera ładunek danych.

# response.choices[0].message.content ma wartość None lub jest puste
# response.choices[0].message.tool_calls zawiera wywołania
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}")

Typowy wynik:

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

Parsowanie odpowiedzi i ekstrakcja tool_calls

Oto kompletny kod do czystego wyodrębnienia informacji z wywołania narzędzia:

message = response.choices[0].message

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

    # Wyodrębnij nazwę funkcji
    function_name = tool_call.function.name

    # Sparsuj argumenty JSON do słownika Python
    function_params = json.loads(tool_call.function.arguments)

    # Pobierz unikalny identyfikator wywołania
    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:
    # Model odpowiedział bezpośrednio
    print(f"Response: {message.content}")

Z tego bloku wynikają trzy elementy informacji, przy czym trzeci jest tym, o którym ludzie zapominają. Nazwa funkcji służy do dyspozytowania, sparsowane argumenty do wykonania wywołania, ale to tool_call_id pozwala modelowi powiązać Twój wynik z właściwym wywołaniem, gdy odsyłasz go z powrotem. Jeśli go zgubisz, wątek rozmowy staje się nie do odzyskania.

Gdy model żąda brakujących informacji

Czasami użytkownik nie podaje wystarczającej ilości informacji. Model ma eleganckie wyjście z tej sytuacji: w ogóle nie wywołuje funkcji, zamiast tego zadaje pytanie doprecyzowujące.

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?"

To zachowanie jest dokładnie tym, czego oczekujesz. Model wie, że transaction_id znajduje się na liście required; zamiast wymyślać prawdopodobny identyfikator i uruchamiać żądanie na nieistniejących danych, oddaje głos użytkownikowi. Jest to również najlepsza demonstracja użyteczności pola required, omówionego w poprzedniej lekcji.

Obsługa wiadomości systemowej

Wiadomość systemowa pozwala Ci ukierunkować to zachowanie, zamiast liczyć na nie przypadkiem.

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?"}
    }
]

Przeczytaj to linijka po linijce: pierwsze zdanie ustala rolę, drugie określa ton i język asystenta, trzecie precyzuje, kiedy używać funkcji, a ostatnie zawiera wyraźną instrukcję dla przypadku brzegowego – brakujących informacji. Są to trzy przypadki użycia, dla których zalecana jest wiadomość systemowa i w większości sytuacji w zupełności wystarczają.

Kompletny kod dla kroków 2–3

Oto kompletny, wielokrotnego użytku kod do wysyłania żądania z narzędziami. Kapsułkuje wszystko, co powyżej, i normalizuje odpowiedź do słownika z dwiema formami, oszczędzając Ci rozpraszania sprawdzeń if message.tool_calls po całej aplikacji.

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:
    """Wysyła żądanie do Mistral z narzędziami i zwraca sparsowaną odpowiedź."""
    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
    }

Zauważ, że wyrażenie listowe iteruje po wszystkich tool_calls, a nie tylko po pierwszym. Model może wygenerować ich kilka naraz; późniejsza lekcja to omówi, ale Twoja funkcja pomocnicza jest już gotowa, aby je obsłużyć.

Kluczowe wnioski

  • Wyślij tools i messages do client.chat.complete(), aby włączyć wywoływanie funkcji
  • Zawsze sprawdzaj, czy message.tool_calls istnieje, zanim spróbujesz je sparsować
  • tool_call_id jest obowiązkowy do odesłania wyniku z powrotem do modelu
  • Argumenty to ciąg JSON, który musi zostać sparsowany za pomocą json.loads()
  • Model może zdecydować się na bezpośrednią odpowiedź, jeśli nie potrzebuje funkcji lub jeśli brakuje informacji