Definirea funcțiilor cu JSON Schema
Pe această pagină
Contractul dintre codul dumneavoastră și model
Pentru ca modelul Mistral să poată apela funcțiile dumneavoastră, acesta trebuie să știe ce există și cum să le utilizeze. Acesta este rolul JSON Schema: un format standardizat care descrie fiecare funcție – numele său, scopul, parametrii așteptați și care dintre aceștia sunt obligatorii.
Rețineți un singur lucru pe tot parcursul acestei lecții: modelul nu vede niciodată codul dumneavoastră Python. El vede doar această specificație. Dacă funcția dumneavoastră gestionează corect ID-urile cu litere mici, dar schema nu menționează acest lucru, modelul va ignora această capacitate. Cu cât schema dumneavoastră este mai precisă și mai bine documentată, cu atât argumentele generate vor fi mai exacte.
Anatomia unei specificații de instrument
Fiecare instrument trimis către API-ul Mistral urmează aceeași structură:
tool = {
"type": "function",
"function": {
"name": "function_name",
"description": "Clear description of what the function does",
"parameters": {
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "Parameter description"
},
"param2": {
"type": "integer",
"description": "Parameter description"
}
},
"required": ["param1"]
}
}
}
| Câmp | Rol |
|---|---|
type | Întotdeauna "function" (alte tipuri pot exista în viitor) |
function.name | Numele exact al funcției dumneavoastră Python – acesta este ceea ce modelul returnează în tool_calls |
function.description | O propoziție clară care ajută modelul să aleagă funcția potrivită |
function.parameters | Un obiect JSON Schema care descrie parametrii așteptați |
required | Lista parametrilor obligatorii |
Tipuri JSON Schema suportate
Vocabularul de tipuri disponibil pentru descrierea parametrilor este intenționat restricționat, iar fiecare tip ghidează modelul diferit. Un enum, în special, face mai mult decât să documenteze: închide ușa valorilor inventate.
# String — text liber sau constrâns
{"type": "string", "description": "Transaction ID"}
# String cu enum — valori limitate
{"type": "string", "enum": ["asc", "desc"], "description": "Sort order"}
# Integer — număr întreg
{"type": "integer", "description": "Number of results to return"}
# Number — număr zecimal
{"type": "number", "description": "Amount in euros"}
# Boolean — true/false
{"type": "boolean", "description": "Include canceled transactions"}
# Array — listă de valori
{
"type": "array",
"items": {"type": "string"},
"description": "List of transaction IDs"
}
# Object — obiect imbricat
{
"type": "object",
"properties": {
"city": {"type": "string"},
"country": {"type": "string"}
},
"description": "Shipping address"
}
Distingeți clar între integer și number: o sumă în euro precum 125.50 necesită un number, în timp ce un număr de rezultate de returnat este un integer. Declararea unei sume ca integer va determina modelul să o rotunjească.
Exemplu complet: două funcții complementare
Iată un exemplu realist cu două funcții legate de plăți, inspirat din documentația oficială Mistral:
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Retrieves the status of a payment (paid, pending, failed) "
"based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "The unique transaction ID (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_date",
"description": "Retrieves the date when a payment was made "
"based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "The unique transaction ID (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
}
]
Ambele funcții așteaptă exact același parametru, transaction_id, totuși modelul trebuie să aleagă între ele. Această alegere se bazează în întregime pe descrierea funcției. „A fost efectuată această plată?“ corespunde lui retrieve_payment_status; „Când a fost efectuată?“ corespunde lui retrieve_payment_date. Dacă ați fi scris două descrieri vagi și interschimbabile, modelul ar fi greșit în jumătate din cazuri – și ați da vina pe model, când greșeala se află în schema dumneavoastră.
Parametri obligatorii vs. opționali
Distincția dintre parametrii obligatorii și cei opționali determină ceea ce modelul are voie să omită.
{
"type": "function",
"function": {
"name": "search_transactions",
"description": "Searches for transactions based on various criteria",
"parameters": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["paid", "pending", "failed"],
"description": "Filter by payment status"
},
"date_from": {
"type": "string",
"description": "Start date in YYYY-MM-DD format"
},
"date_to": {
"type": "string",
"description": "End date in YYYY-MM-DD format"
},
"min_amount": {
"type": "number",
"description": "Minimum amount in euros"
}
},
"required": ["status"]
}
}
}
Aici, doar status este obligatoriu; ceilalți parametri sunt incluși doar dacă utilizatorul îi menționează. Comparați două formulări. Pentru „Arată-mi plățile eșuate“, modelul generează simplu {"status": "failed"}. Pentru „Arată-mi plățile eșuate din martie 2026“, acesta adaugă singur date_from și date_to. Declararea acestor date ca obligatorii ar fi stricat prima interogare sau, mai rău, ar fi împins modelul să inventeze un interval de date.
Cele mai bune practici pentru descrieri
Calitatea descrierilor impactează direct acuratețea modelului. Contra-exemplele de mai jos sunt mai instructive decât orice regulă abstractă.
# Rău — prea vag
{"description": "Retrieves data"}
# Bun — precis și contextual
{"description": "Retrieves the status of a payment (paid, pending, failed) "
"based on the unique transaction ID"}
# Rău — fără descriere pentru parametru
{"transaction_id": {"type": "string"}}
# Bun — descriere cu exemplu
{"transaction_id": {
"type": "string",
"description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}
O descriere bună enunță într-o singură propoziție ce face funcția, specifică formatul așteptat pentru fiecare parametru și oferă un exemplu ori de câte ori acel format nu este evident – T1001 este mai bun decât „ID tranzacție“. Când valorile posibile sunt limitate, nu le descrieți în proză: declarați-le cu enum. Aceasta este singura modalitate de a le face obligatorii.
Puncte cheie
- JSON Schema este contractul dintre codul dumneavoastră și model – acesta descrie funcțiile dumneavoastră fără a expune codul
- Fiecare instrument are un
name, odescriptionșiparameterstipizați - Tipurile suportate includ
string,integer,number,boolean,arrayșiobject - Lista
requireddistinge parametrii obligatorii de cei opționali - Descrierile precise cu exemple îmbunătățesc semnificativ acuratețea modelului