Извикване на API с инструменти
На тази страница
Изпращане на инструменти към 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() - Моделът може да избере да отговори директно, ако не му е необходима функция или ако липсва информация