Kutsu API:a työkalujen avulla
Tällä sivulla
Lähetä työkalut Mistral API:lle
Olet määritellyt funktiosi ja niiden JSON-määrittelyt. Nyt sinun täytyy lähettää ne Mistral API:lle ja ennen kaikkea ymmärtää, mitä malli palauttaa. Olemme nyt prosessin vaiheissa 2 ja 3: malli vastaanottaa käyttäjän pyynnön yhdessä työkalujen kanssa ja tuottaa funktiokutsun – tai kieltäytyy tekemästä sellaista, mikä on yhtä lailla opettavaista.
Ensimmäinen pyyntö
import os
import json
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Edellisellä tunnilla määritellyt työkalut
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"]
}
}
}
]
# Käyttäjän viesti
messages = [
{"role": "user", "content": "What is the status of payment T1001?"}
]
# API-kutsu työkalujen kanssa
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools
)
Mallin vastauksen ymmärtäminen
Vastaus sisältää message-objektin, joka voi esiintyä kahdessa muodossa, ja koodisi tulee käsitellä molemmat alusta alkaen. Ensimmäisessä tapauksessa malli vastaa suoraan, koska funktiota ei tarvita: content sisältää tekstiä ja tool_calls on None.
# response.choices[0].message.content sisältää tekstivastauksen
# response.choices[0].message.tool_calls on None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"
Toisessa tapauksessa malli haluaa kutsua funktion. Tilanne kääntyy päinvastaiseksi: content on tyhjä tai null, ja tool_calls sisältää hyötykuorman.
# response.choices[0].message.content on None tai tyhjä
# response.choices[0].message.tool_calls sisältää kutsut
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}")
Tyypillinen tuloste:
Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz
Vastauksen jäsentäminen ja tool_calls-tietojen erottelu
Tässä on täydellinen koodi tietojen siistiseen erotteluun työkalukutsusta:
message = response.choices[0].message
if message.tool_calls and len(message.tool_calls) > 0:
tool_call = message.tool_calls[0]
# Erottele funktion nimi
function_name = tool_call.function.name
# Jäsennä JSON-argumentit Python-sanakirjaksi
function_params = json.loads(tool_call.function.arguments)
# Hae yksilöllinen kutsutunniste
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:
# Malli vastasi suoraan
print(f"Response: {message.content}")
Tästä lohkosta nousee esiin kolme tietoa, joista kolmas on se, jonka ihmiset usein unohtavat. Funktionimeä käytetään reititykseen, jäsennettyjä argumentteja kutsun suorittamiseen, mutta tool_call_id on se, jonka avulla malli voi yhdistää tuloksesi oikeaan kutsuun, kun lähetät sen takaisin. Jos hukkaat sen, keskustelukierroksesta tulee palautumaton.
Kun malli pyytää puuttuvia tietoja
Joskus käyttäjä ei anna tarpeeksi tietoa. Mallilla on tähän elegantti ratkaisu: älä kutsu funktiota lainkaan, vaan esitä sen sijaan tarkentava kysymys.
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?"
Tämä käyttäytyminen on täsmälleen sitä, mitä haluat. Malli tietää, että transaction_id on listattu kohtaan required; sen sijaan että se keksisi uskottavan tunnisteen ja laukaisisi pyynnön olemattomille tiedoille, se luovuttaa vuoron käyttäjälle. Tämä on myös paras osoitus edellisellä tunnilla käsitellyn required-kentän hyödyllisyydestä.
Järjestelmäviestin käsittely
Järjestelmäviestin avulla voit kehystää tätä käyttäytymistä sen sijaan, että toivoisit sen tapahtuvan itsestään.
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?"}
}
]
Lue se rivi riviltä: ensimmäinen lause määrittää roolin, toinen asettaa avustajan sävyn ja kielen, kolmas täsmentää, milloin funktioita tulee käyttää, ja viimeinen antaa nimenomaisen ohjeen reunatapaukseen – puuttuvat tiedot. Nämä ovat kolme käyttötapausta, joissa järjestelmäviestiä suositellaan, ja ne riittävät useimmissa tilanteissa.
Täydellinen koodi vaiheisiin 2–3
Tässä on täydellinen, uudelleenkäytettävä koodi pyynnön lähettämiseen työkalujen kanssa. Se kapseloi kaiken edellä mainitun ja normalisoi vastauksen sanakirjaksi, jossa on kaksi muotoa, mikä säästää sinua sirpaloimasta if message.tool_calls-tarkistuksia sovelluksesi eri puolille.
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:
"""Lähettää pyynnön Mistralille työkalujen kanssa ja palauttaa jäsennetyn vastauksen."""
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
}
Huomaa, että listakooste iteroi kaikkien tool_calls-kohteiden yli, ei vain ensimmäisen. Malli voi tuottaa useita kerralla; myöhempi tunti käsittelee tätä, mutta apufunktiosi on jo valmis käsittelemään ne.
Keskeiset asiat
- Lähetä
toolsjamessagesfunktioonclient.chat.complete()ottaaksesi funktiokutsut käyttöön - Tarkista aina, onko
message.tool_callsolemassa, ennen kuin yrität jäsentää sitä tool_call_idon pakollinen, kun lähetät tuloksen takaisin mallille- Argumentit ovat JSON-merkkijono, joka on jäsennettävä funktiolla
json.loads() - Malli voi päättää vastata suoraan, jos se ei tarvitse funktiota tai jos tietoja puuttuu