Käytännöt ja tuotantokäyttö
Tällä sivulla
Prototyypistä tuotantoon
Sinulla on nyt kaikki rakennuspalikat Mistralin funktiokutsujärjestelmien rakentamiseen. Prototyyppisi ja tuotantovalmiin palvelun välinen ero ei ole puuttuvissa ominaisuuksissa, vaan tarkistus- ja viritysvaiheissa, jotka yleensä paljastuvat vasta häiriötilanteissa. Tämä viimeinen oppitunti kokoaa yhteen parhaat käytännöt, yleisimmät sudenkuopat ja tarkistuslistan, jotta voit siirtyä tuotantoon luottavaisin mielin.
Käyttöönoton tarkistuslista
Tämä on ainoa kohta kurssilla, jossa luettelomuoto on pakollinen: ennen julkaisua rastitat ruudut. Neljän alueen on katettava kaikki, ja jokainen vastaa eri kysymykseen.
Arkkitehtuuri varmistaa, että mekanismit kestävät. JSON-merkkijonojen palauttaminen ketjussa ja täydellinen dispatch-sanakirja ovat kaksi yleisintä syytä kaatumisille ensimmäisessä todellisessa kutsussa.
- Kaikki funktiot palauttavat JSON-merkkijonoja (ei koskaan raakoja Python-olioita)
- Dispatch-sanakirja on täydellinen ja ajan tasalla
- Funktiot käsittelevät virhetilanteet ja palauttavat käyttökelpoisia viestejä
- Järjestelmäviesti on selkeä, tarkka ja testattu
- Keskustelusilmukka käsittelee sekä peräkkäiset että rinnakkaiset kutsut
Turvallisuus olettaa, että argumentit tulevat käyttäjältä, eivät sovellukseltasi.
- Argumentit validoidaan ennen suorittamista (muoto, tyyppi, arvot)
- SQL-kyselyt käyttävät parametreja (ei merkkijonoliitosta)
- Valkolista rajoittaa käytettävissä olevia funktioita
- Tuhoisat toiminnot vaativat vahvistuksen
- Nopeusrajoitus on käytössä funktiokohtaisesti ja käyttäjäkohtaisesti
- Tulokset puhdistetaan (arkaluonteisia tietoja ei palauteta mallille)
Luotettavuus käsittelee tilanteet, joissa jotain epäonnistuu ilman kenenkään syytä.
- Virheet palautetaan mallille jäsennellyssä muodossa
- Uudelleenyritys eksponentiaalisella viiveellä (backoff) on toteutettu ohimeneviä virheitä varten
- Aikakatkaisut on määritetty jokaiselle ulkoiselle funktiolle
- Historian koko on rajoitettu token-ylijäämien välttämiseksi
Seuranta puolestaan mahdollistaa vianmäärityksen ilman arvailua.
- Jokainen funktiokutsu lokitetaan (nimi, argumentit, tulos, kesto)
- Virheet laukaisevat hälytyksiä (Slack, PagerDuty jne.)
- Mittareita kerätään (onnistumisprosentti, viive, API-kustannukset)
Kuvausten kirjoittaminen, jotka saavat mallin toimimaan
Kuvausten laadulla on suora vaikutus tarkkuuteen, ja se on usein edullisin vipu, jota voit liikuttaa. Kolme mallia toistuu tiimeillä, joilla on korkeat oikeiden kutsujen määrät. Ensimmäinen ankkuroi kuvauksen liiketoimintakontekstiin: funktion nimen uudelleenmuotoilun sijaan listaa mahdolliset palautusarvot ja määritä eksplisiittisesti, milloin sitä tulee kutsua. Toinen sisällyttää muotoesimerkkejä parametrin kuvaukseen, mikä korjaa useimmat ID-tunnisteiden poimintavirheet. Kolmas korvaa luonnollisen kielen ohjeen enum:lla, mikä on ainoa tapa todella kieltää arvon käyttö listan ulkopuolelta.
# Malli 1: Kuvaus liiketoimintakontekstilla
{
"description": "Hakee maksun tilan. "
"Mahdolliset tilat: paid, pending, failed, refunded. "
"Käytä tätä funktiota, kun käyttäjä kysyy "
"maksun tilasta tai siitä, onko se vastaanotettu."
}
# Malli 2: Parametrit esimerkkeineen
{
"transaction_id": {
"type": "string",
"description": "Unikki ID muodossa T ja 4 numeroa (esim. T1001, T2345)"
}
}
# Malli 3: Enum rajoitetuille arvoille
{
"status": {
"type": "string",
"enum": ["paid", "pending", "failed", "refunded"],
"description": "Suodata maksutilan perusteella"
}
}
Oikean mallin valinta
Mallin valinta on kompromissi tarkkuuden ja kustannusten välillä, eikä universaalia vastausta ole: se riippuu eksponoitujen funktioiden määrästä ja niiden skeemojen monimutkaisuudesta. Monimutkainen tapaus, jossa on paljon funktioita ja sisäkkäisiä parametreja, perustelee Mistral Large 3:n käytön, joka on luotettavampi funktion valinnassa mutta kalliimpi. Tavallinen tapaus, jossa on muutama yksinkertainen funktio suurta läpimenoa vaativassa tuotannossa, toimii erinomaisesti Mistral Small 4:llä, joka on nopea ja taloudellinen. Prototypointiin ja testaukseen Mistral Medium 3.5 tarjoaa hyvän kompromissin.
# Monimutkaiset tapaukset: paljon funktioita, sisäkkäiset parametrit
# -> Mistral Large 3 (luotettavampi, kalliimpi)
model = "mistral-large-latest"
# Tavalliset tapaukset: muutama yksinkertainen funktio, suurta läpimenoa vaativa tuotanto
# -> Mistral Small 4 (nopea, taloudellinen)
model = "mistral-small-latest"
# Kehitystapaukset: prototypointi, testaus
# -> Mistral Medium 3.5 (hyvä kompromissi)
model = "mistral-medium-latest"
Menetelmä on yhtä tärkeä kuin tulos: aloita tuotannossa kyvykkäimmällä mallilla, mittaa oikeiden kutsujen prosenttiosuus ja siirry sitten vähitellen alaspäin löytääksesi parhaan kustannus-tehokkuussuhteen. Päinvastainen lähestymistapa – halvimman mallin käyttäminen alusta alkaen – vie sinulta pohjatiedon, jota tarvitset sen selvittämiseen, johtuuko heikkeneminen mallista vai kuvauksistasi.
Järjestelmäviestin rakentaminen
Hyvä järjestelmäviesti tekee eron keskinkertaisen ja erinomaisen avustajan välillä. Tämä esimerkki havainnollistaa toimivaksi todettua rakennetta: roolin määrittely, lohko imperatiivisia sääntöjä ja muistutus käytettävissä olevista työkaluista. Kaksi kustannustehokkainta sääntöä tässä ovat “Jos käyttäjä ei anna vaadittavaa ID:tä, kysy sitä kohteliaasti” ja “Älä koskaan arvaa transaktio-ID:tä” – yhdessä ne eliminoivat kaikkein vahingollisimman käyttäytymisen, eli funktion kutsumisen keksityllä ID:llä.
system_message = {
"role": "system",
"content": """Olet Acme Corporationin maksunhallinta-avustaja.
Säännöt:
- Vastaa aina englanniksi
- Muotoile summat euroina symbolilla ja kahdella desimaalilla
- Jos käyttäjä ei anna vaadittavaa ID:tä, kysy sitä kohteliaasti
- Älä koskaan arvaa transaktio-ID:tä
- Kun transaktio epäonnistuu, tarjoa tarkistaa yksityiskohdat
Käytettävissä olevat työkalut:
- retrieve_payment_status: tarkistaa maksun tilan
- retrieve_payment_date: tarkistaa maksun päivämäärän
- retrieve_payment_details: hakee kaikki transaktion yksityiskohdat
- list_customer_transactions: näyttää kaikki asiakkaan transaktiot"""
}
Kustannusten hallinta tuotannossa
Jokainen funktiokutsu kuluttaa tokeneja, ja lasku kasvaa kahden aliarvioidun kanavan kautta: työkalumääritelmät lähetetään jokaisen pyynnön mukana, ja historia kasvaa jokaisella vuorolla. Funktioiden suodattaminen kontekstin perusteella ratkaisee ensimmäisen kohdan – kaikkia kahtatoista työkalua ei tarvitse lähettää, kun kysymys koskee selkeästi maksuja. Historian typistäminen kynnyksen yli ratkaisee toisen. Ja kun kaikki tarvittava data on jo kontekstissa, tool_choice="none" välttää ylimääräisen kierroksen.
# 1. Rajoita funktioiden määrää pyyntöä kohden
# Lähetä vain kontekstiin sopivat funktiot
def get_relevant_tools(user_input: str, all_tools: list) -> list:
"""Suodattaa työkalut kontekstin perusteella."""
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. Rajoita historian kokoa
MAX_HISTORY = 20 # viestejä
# 3. Käytä tool_choice="none", kun data on jo saatavilla
Funktiokutsujen testaaminen
Testit ovat välttämättömiä regressioiden välttämiseksi, ja tässä ne kohdistuvat epätavalliseen kohteeseen: et tarkista funktion palautusarvoa, vaan mallin päätöstä. Kaksi testiperhettä kattaa oleelliset asiat. Ensimmäinen varmistaa, että liiketoimintakysymys laukaisee oikean funktion oikeilla poimituilla argumenteilla. Toinen, yhtä tärkeä ja usein unohdettu, varmistaa, että tervehdys ei laukaise kutsua – tämä testi paljastaa liian laajat kuvaukset, jotka pakottavat mallin kutsumaan funktiota kaikissa tilanteissa.
def test_payment_status():
"""Testaa, että malli kutsuu oikeaa funktiota."""
messages = [{"role": "user", "content": "Maksun T1001 tila?"}]
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():
"""Testaa, että malli ei kutsu funktiota tervehdykseen."""
messages = [{"role": "user", "content": "Hei!"}]
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
Seuranta tuotannossa
Nyt sinun on tiedettävä, mitä järjestelmäsi tekee päästyään vapaaseen luontoon. Alla oleva luokka aggregoi kolme signaalia, jotka yhdessä kertävät lähes koko tarinan: yleinen onnistumisprosentti, keskimääräinen viive ja erittely funktioittain. Viimeinen on käytännössä paljastavin – funktio, jonka virhelaskuri kasvaa eristyksissä, viittaa tiettyyn ongelmaan, kun taas heikentynyt yleinen prosentti ei kerro mitään siitä, mistä etsiä.
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()
Seuraavat askeleet
Nyt kun hallitset funktiokutsut Mistralilla, useita suuntia avautuu. Luonnollisin on autonomisten agenttien rakentaminen, yhdistämällä funktiokutsut agenttisilmukkaan, joka suunnittelee ja suorittaa monimutkaisia tehtäviä; Mistral Agents API ja sen client.beta.agents.create() vievät tämän pidemmälle tarjoamalla tilallisia pysyviä agentteja. Toinen akseli yhdistää RAG:n ja funktiokutsut: malli päättää itse, milloin kysyä vektoritietokannalta, sen sijaan että haku laukaistaisiin systemaattisesti etukäteen. Käyttökokemuksen näkökulmasta streaming mahdollistaa vastausten näyttämisen reaaliajassa funktioiden suorituksen aikana, mikä muuttaa viiveen havaintoa pitkissä kutsuketjuissa. Lopuksi multimodaalisuus avaa funktiokutsut näkökyvylle dokumenttianalyysiä varten.
Keskeiset asiat
- Käyttöönoton tarkistuslista kattaa arkkitehtuurin, turvallisuuden, luotettavuuden ja seurannan
- Tarkat kuvaukset esimerkkeineen ja enum-arvoineen parantavat mallin tarkkuutta
- Valitse oikea malli monimutkaisuuden ja budjetin perusteella (Large luotettavuuteen, Small läpimenoon)
- Järjestelmäviesti on tehokas vipu käyttäytymisen ohjaamiseen
- Testaa funktiokutsut ja ei-funktio-käyttäytyminen systemaattisesti
- Seuraa onnistumisprosenttia, viivettä ja kustannuksia tuotannossa
Testaa tietosi
End-to-end-funktiokutsut: viisi tarkistusta.
1. Mitkä ovat funktiokutsujen viisi vaihetta?
Vastaus: Määritä funktiot (skeemat), anna ne API:lle, malli pyytää kutsua argumentteineen, koodisi suorittaa ja palauttaa tuloksen, malli tuottaa lopullisen vastauksen.
2. Mikä tekee hyvästä funktioskeemasta?
Vastaus: Tiukat tyypit ja operatiiviset kuvaukset – selkeä nimi, milloin sitä käytetään, kunkin parametrin muoto: tämä on teksti, jonka malli lukee päättääkseen ja täyttääkseen arvot.
3. Mitä rinnakkaiset kutsut mahdollistavat?
Vastaus: Malli pyytää useita funktioita yhdessä vastauksessa, kun ne ovat toisistaan riippumattomia – vähemmän kierroksia, edellyttäen että yhdistät jokaisen tuloksen oikeaan kutsuun.
4. Mihin tool_choice:a käytetään?
Vastaus: Määrittämään mallin vapausaste: auto (se päättää), any (sen on käytettävä työkalua) tai pakotettu työkalu – viimeinen on avain luotettavaan jäsenneltyyn poimintaan.
5. Mitkä turvallisuussäännöt koskevat eksponoituja funktioita?
Vastaus: Validoi vastaanotetut argumentit, rajoita kunkin funktion laajuutta, lokita kutsut ja pidä ihmisen validointi sitovia toimia varten – malli ehdottaa, koodisi päättää.
Tämän kurssin kaksi käytännön esimerkkiä (maksuseuranta, CRM) noudattavat täsmälleen näitä sääntöjä – omat integraatiosi seuraavat samaa kaavaa.