Parimad tavad ja tootmine
Sellel lehel
Tõestuskontseptist tootmiseni
Sul on nüüd olemas kõik vajalikud komponendid Mistrali funktsioonide kutsumise süsteemide loomiseks. Sinu prototüüpi ja tootmisvalmis teenust ei eralda mitte puuduvad funktsioonid, vaid kontrollide ja häälestuste seeria, mille avastad tavaliselt intsidenti käigus. See viimane õppetund koondab parimad tavad, levinumad lõksud ja kontrollnimekirja, et liikuda tootmisse kindlustundega.
Kasutuselevõtu kontrollnimekiri
See on ainus koht selles kursuses, kus loendiformaat on kohustuslik: enne live’i minekut linnukesed tehtud. Katta tuleb neli valdkonda, millest igaüks vastab erinevale küsimusele.
Arhitektuur tagab, et mehhanismid peavad vastu. JSON-stringide tagastamine ahelas ja täieliku dispatch-sõnastiku olemasolu on kaks kõige sagedasemat põhjust, miks süsteem esimesel reaalsel väljakutsel kokku jookseb.
- Kõik funktsioonid tagastavad JSON-stringe (mitte kunagi tooreid Pythoni objekte)
- Dispatch-sõnastik on täielik ja ajakohane
- Funktsioonid käsitlevad veajuhtumeid ja tagastavad kasutatavaid sõnumeid
- Süsteemisõnum on selge, täpne ja testitud
- Vestlutsükkel käsitleb järjestikuseid ja paralleelseid väljakutseid
Turvalisus eeldab, et argumendid pärinevad kasutajalt, mitte kunagi sinu rakenduselt.
- Argumendid valideeritakse enne käivitamist (vorming, tüüp, väärtused)
- SQL-päringud kasutavad parameetreid (ei mingit liitmist)
- Valge nimekiri piirab saadaolevaid funktsioone
- Destruktiivsed tegevused nõuavad kinnitust
- Kiiruse piiramine on rakendatud iga funktsiooni ja kasutaja kohta
- Tulemused puhastatakse (mudelitele ei tagastata tundlikke andmeid)
Töökindlus käsitleb olukordi, kus midagi läheb valesti ilma kellegi süüta.
- Vead tagastatakse mudelile struktureeritud vormingus
- Mööduvate vigade jaoks on rakendatud taaskäivitamine viivitusega (retry with backoff)
- Iga väliste funktsiooni jaoks on konfigureeritud ajalõpid
- Ajaloo suurust on piiratud, et vältida tokenite ületamist
Monitooring on lõpuks see, mis võimaldab diagnoosida ilma arvamiseta.
- Iga funktsiooni kutsumine logitakse (nimi, argumendid, tulemus, kestus)
- Vead käivitavad hoiatusi (Slack, PagerDuty jne)
- Mõõdikuid kogutakse (edumäär, latentsus, API kulud)
Kirjelduste koostamine, mis paneb mudeli tööle
Kirjelduste kvaliteet mõjutab otseselt täpsust ja see on sageli odavaim hoob, mida tõmmata. Kolm mustrit korduvad meeskondades, kus on kõrge korrektsete kutsete määr. Esimene ankurdab kirjelduse ärikonteksti: funktsiooni nime ümber sõnastamise asemel loetle võimalikud tagastusväärtused ja sätesta selgelt, millal seda kutsuda. Teine sisestab vormingu näited parameetri kirjeldusse, mis lahendab enamiku ID-de ekstraheerimise vigadest. Kolmas asendab loomuliku keele juhise enum-iga, mis on ainus viis keelata väärtus väljaspool loetelu.
# Muster 1: Kirjeldus ärikontekstiga
{
"description": "Toob välja makse staatuse. "
"Võimalikud staatused: paid, pending, failed, refunded. "
"Kasuta seda funktsiooni, kui kasutaja küsib "
"makse staatuse kohta või seda, kas see on laekunud."
}
# Muster 2: Parameetrid näidetega
{
"transaction_id": {
"type": "string",
"description": "Unikaalne ID formaadis T, millele järgneb 4 numbrit (nt T1001, T2345)"
}
}
# Muster 3: Enum piiratud väärtuste jaoks
{
"status": {
"type": "string",
"enum": ["paid", "pending", "failed", "refunded"],
"description": "Filtreeri makse staatuse järgi"
}
}
Õige mudeli valimine
Mudeli valik on kompromiss täpsuse ja kulu vahel ning universaalset vastust pole: see sõltub avaldatud funktsioonide arvust ja nende skeemide keerukusest. Kompleksne juhtum paljude funktsioonide ja pesastatud parameetritega õigustab Mistral Large 3 kasutamist, mis on funktsioonide valikul usaldusväärsem, kuid kallim. Standardne juhtum mõne lihtsa funktsiooniga suure läbilaskevõimega tootmises töötab väga hästi Mistral Small 4 peal, mis on kiire ja ökonoomne. Prototüüpimiseks ja testimiseks pakub Mistral Medium 3.5 head kompromissi.
# Komplekssed juhtumid: palju funktsioone, pesastatud parameetrid
# -> Mistral Large 3 (usaldusväärsem, kallim)
model = "mistral-large-latest"
# Standardsed juhtumid: vähe lihtsaid funktsioone, suure läbilaskevõimega tootmine
# -> Mistral Small 4 (kiire, ökonoomne)
model = "mistral-small-latest"
# Arendusjuhtumid: prototüüpimine, testimine
# -> Mistral Medium 3.5 (hea kompromiss)
model = "mistral-medium-latest"
Meetod on sama oluline kui tulemus: tootmises alusta võimekaima mudeliga, mõõda oma korrektsete kutsete määra ja liigu seejärel järk-järgult allapoole, et leida parim kulu/jõudluse suhe. Vastupidine lähenemine – alustamine odavaima mudeliga – jätab sind ilma baasjoonest, mida on vaja teadmaks, kas halvenemine tuleneb mudelist või sinu kirjeldustest.
Süsteemisõnumi struktureerimine
Hea süsteemisõnum teeb vahet keskpärase ja suurepärase assistendi vahel. See illustreerib tõestatud struktuuri: rolli väide, imperatiivsete reeglite plokk ja seejärel meeldetuletus saadaolevate tööriistade kohta. Kaks kuluefektiivseimat reeglit siin on „Kui kasutaja ei esita nõutavat ID-d, küsi viisakalt“ ja „Ära kunagi arvake tehingu ID-d“ – koos kõrvaldavad need kõige kahjulikuma käitumise, nimelt funktsiooni kutsumise väljamõeldud ID-ga.
system_message = {
"role": "system",
"content": """Oled Acme Corporationi maksehalduse assistent.
Reeglid:
- Vasta alati inglise keeles
- Vorminda summad eurodes sümboli ja kahe komakohaga
- Kui kasutaja ei esita nõutavat ID-d, küsi viisakalt
- Ära kunagi arvake tehingu ID-d
- Kui tehing ebaõnnestub, paku välja detailide kontrollimine
Saadaolevad tööriistad:
- retrieve_payment_status: makse staatuse kontrollimiseks
- retrieve_payment_date: makse kuupäeva kontrollimiseks
- retrieve_payment_details: tehingu kõigi detailide saamiseks
- list_customer_transactions: kliendi kõigi tehingute vaatamiseks"""
}
Kulude haldamine tootmises
Iga funktsiooni kutsumine tarbib tokeneid ja arve kasvab kahe alahinnatud kanali kaudu: tööriistade definitsioonid saadetakse iga päringuga ja ajaloo kasvab iga vooruga. Funktsioonide filtreerimine konteksti põhjal lahendab esimese punkti – pole vaja saata kõiki kahteist tööriista, kui küsimus puudutab selgelt makseid. Ajaloo lühendamine üle läve lahendab teise. Ja kui kõik vajalikud andmed on juba kontekstis olemas, väldib tool_choice="none" täiendavat vooru.
# 1. Piira funktsioonide arvu päringu kohta
# Edasta ainult kontekstiga seotud funktsioonid
def get_relevant_tools(user_input: str, all_tools: list) -> list:
"""Filtreerib tööriistu konteksti põhjal."""
if "payment" in user_input.lower() or "transaction" in user_input.lower():
return [t for t in all_tools if "payment" in t["function"]["name"]]
if "contact" in user_input.lower() or "customer" in user_input.lower():
return [t for t in all_tools if "contact" in t["function"]["name"]]
return all_tools
# 2. Piira ajaloo suurust
MAX_HISTORY = 20 # sõnumit
# 3. Kasuta tool_choice="none", kui andmed on juba olemas
Funktsioonide kutsumise testimine
Testid on tagasiminekute vältimiseks hädavajalikud ja siin on sihiks ebatavaline objekt: sa ei kontrolli oma funktsiooni tagastusväärtust, vaid mudeli otsust. Kaks testide perekonda katavad põhiosa. Esimene kontrollib, kas äriküsimus käivitab õige funktsiooni õigesti ekstraheeritud argumentidega. Teine, sama oluline ja sageli unustatud, kontrollib, kas tervitus ei käivita ühtegi kutset – see test püüab kinni liiga laiad kirjeldused, mis sunnivad mudelit igas olukorras funktsiooni kutsuma.
def test_payment_status():
"""Testib, et mudel kutsub õiget funktsiooni."""
messages = [{"role": "user", "content": "Makse T1001 staatus?"}]
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
message = response.choices[0].message
assert message.tool_calls is not None
assert len(message.tool_calls) == 1
assert message.tool_calls[0].function.name == "retrieve_payment_status"
args = json.loads(message.tool_calls[0].function.arguments)
assert args["transaction_id"] == "T1001"
def test_no_function_for_greeting():
"""Testib, et mudel ei kutsu tervituse korral funktsiooni."""
messages = [{"role": "user", "content": "Tere!"}]
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
message = response.choices[0].message
assert message.tool_calls is None or len(message.tool_calls) == 0
assert message.content is not None
Monitooring tootmises
Nüüd pead teadma, mida sinu süsteem teeb, kui see on vabaks lastud. Allpool olev klass koondab kolm signaali, mis koos räägivad peaaegu kogu loo: üldine edumäär, keskmine latentsus ja jaotus funktsioonide kaupa. Viimane on praktikas kõige kõnekam – funktsioon, mille vealoendur isoleeritult kasvab, osutab konkreetsele probleemile, samas kui halvenenud üldmäär ei ütle sulle midagi selle kohta, kuhu vaadata.
import time
import logging
logger = logging.getLogger("fc_monitor")
class FunctionCallingMonitor:
def __init__(self):
self.metrics = {
"total_calls": 0,
"successful_calls": 0,
"failed_calls": 0,
"total_latency_ms": 0,
"calls_by_function": {}
}
def record(self, function_name: str, success: bool, latency_ms: float):
self.metrics["total_calls"] += 1
self.metrics["total_latency_ms"] += latency_ms
if success:
self.metrics["successful_calls"] += 1
else:
self.metrics["failed_calls"] += 1
if function_name not in self.metrics["calls_by_function"]:
self.metrics["calls_by_function"][function_name] = {
"count": 0, "errors": 0
}
self.metrics["calls_by_function"][function_name]["count"] += 1
if not success:
self.metrics["calls_by_function"][function_name]["errors"] += 1
def get_success_rate(self) -> float:
if self.metrics["total_calls"] == 0:
return 0.0
return self.metrics["successful_calls"] / self.metrics["total_calls"]
def get_avg_latency(self) -> float:
if self.metrics["total_calls"] == 0:
return 0.0
return self.metrics["total_latency_ms"] / self.metrics["total_calls"]
monitor = FunctionCallingMonitor()
Järgmised sammud
Nüüd, kui oled Mistraliga funktsioonide kutsumise omandanud, avaneb mitu suunda. Kõige loomulikum on ehitada autonoomseid agente, kombineerides funktsioonide kutsumist agendi tsükliga, mis planeerib ja täidab keerukaid ülesandeid; Mistral Agents API ja selle client.beta.agents.create() lähevad kaugemale, pakkudes püsivaid olekuga agente. Teine telg ühendab RAG-i ja funktsioonide kutsumise: mudel otsustab ise, millal pärida vektorandmebaasi, selle asemel et otsingut süstemaatiliselt eelnevalt käivitataks. Kasutajakogemuse poolelt võimaldab voogedastus (streaming) kuvada vastuseid reaalajas samal ajal, kui funktsioonid täidetakse, muutes latentsuse tajumist pikkades kutseahelates. Lõpuks avab multimodaalsus funktsioonide kutsumise nägemisele dokumentide analüüsimiseks.
Peamised punktid
- Kasutuselevõtu kontrollnimekiri hõlmab arhitektuuri, turvalisust, töökindlust ja monitooringut
- Täpsed kirjeldused koos näidete ja enum-idega parandavad mudeli täpsust
- Vali õige mudel lähtudes keerukusest ja eelarvest (Large usaldusväärsuse jaoks, Small läbilaskevõime jaoks)
- Süsteemisõnum on võimas hoob käitumise juhtimiseks
- Testi funktsioonide kutseid ja käitumist ilma funktsioonita süstemaatiliselt
- Monitori tootmises edumäära, latentsust ja kulusid
Testi oma teadmisi
Otsast otsani funktsioonide kutsumine: viis kontrolli.
1. Millised on funktsioonide kutsumise viis sammu?
Vastus: Määratle funktsioonid (skeemid), edasta need API-le, mudel taotleb kutset koos oma argumentidega, sinu kood käivitab ja tagastab tulemuse, mudel genereerib lõpliku vastuse.
2. Mis teeb funktsiooni skeemi heaks?
Vastus: ranged tüübid ja operatiivsed kirjeldused – selge nimi, millal seda kasutada, iga parameetri vorming: see on tekst, mida mudel loeb otsustamiseks ja täitmiseks.
3. Mida võimaldavad paralleelsed kutsed?
Vastus: Mudel taotleb mitut funktsiooni ühes vastuses, kui need on sõltumatud – vähem voore, eeldusel, et sobitad iga tulemuse oma kutsega.
4. Milleks on tool_choice?
Vastus: Mudeli vabaduse määramiseks: auto (otsustab ise), any (peab kasutama tööriista) või sunnitud tööriist – viimane on võtmetähtsusega usaldusväärseks struktureeritud ekstraheerimiseks.
5. Millised turvareeglid kehtivad avaldatud funktsioonidele?
Vastus: Valideeri saadud argumendid, piira iga funktsiooni ulatust, logi kutsed ja hoia inimkinnitus toimingute kinnitamisel – mudel teeb ettepaneku, sinu kood otsustab.
Selles kursuses käsitletud kaks näidet (maksete jälgija, CRM) rakendavad täpselt neid reegleid – ka sinu enda integratsioonid järgivad sama malli.