Wywołaj API za pomocą narzędzi
Na tej stronie
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
toolsimessagesdoclient.chat.complete(), aby włączyć wywoływanie funkcji - Zawsze sprawdzaj, czy
message.tool_callsistnieje, zanim spróbujesz je sparsować tool_call_idjest 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