Parhaat käytännöt ja yhteenveto
Tällä sivulla
Kurssin yhteenveto
Olet tutustunut Mistral API:n tarjoamiin strukturoitujen tulosteiden mekanismeihin koko laajuudessaan. Tämä viimeinen oppitunti kokoaa yhteen ne tekijät, jotka tekevät eron arkityössä: miten valita kahden lähestymistavan välillä, mitkä asetukset ovat ehdottomia, mitkä ovat yleisimmät sudenkuopat ja mitä tulee seurata, kun järjestelmäsi on tuotannossa.
Lähestymistavan valinta
Neljä kysymystä riittää päätöksentekoon, tässä järjestyksessä. Onko sinulla määritelty tulosteskeema? Jos vastaus on ei, pysy JSON-tilassa: olet tutkimus- tai prototyyppivaiheessa, ja datamallin lukitseminen olisi ennenaikaista. Jos kyllä, siirry seuraavaan kysymykseen.
Käytätkö Pythonia vai TypeScriptiä? Jos käytät, mukautetut strukturoidut tulosteet ovat valmiina käyttöön Pydanticin tai Zodin kautta. Jos et, JSON-tila manuaalisella validoinnilla on polkusi.
Oletko tuotantoympäristössä? Jos olet, mukautetut strukturoidut tulosteet ovat aina pakollisia. Muutoin JSON-tila on enemmän kuin riittävä prototyyppaukseen.
Muuttuuko skeema usein? Jatkuvasti kehittyvä skeema tekee JSON-tilasta käytännöllisemmän aluksi, kunnes vaatimukset vakiintuvat; kiinteä skeema puolestaan puhuu mukautettujen strukturoitujen tulosteiden ja niiden tuoman luotettavuuden puolesta.
Kymmenen kultainen sääntöä
Viisi ensimmäistä koskee kutsujen kirjoittamista. Aseta aina temperature=0 tuotannossa: lämpötilan vaihtelu on luotettavuuden vihollinen, eikä tiedonpoiminta kaipaa luovuutta.
# Tuotanto: deterministinen
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
temperature=0 # Toistettavuus
)
Tarkista aina finish_reason. Tämä on ainoa indikaattori, joka varoittaa sinua typistyneestä vastauksesta ennen sen käyttämistä.
if response.choices[0].finish_reason != "stop":
# Vastaus on typistynyt — kasvata max_tokens-arvoa
raise ValueError(f"Puutteellinen vastaus: {response.choices[0].finish_reason}")
JSON-tilassa kehota mallia aina kehotteessa (prompt). Parametri takaa syntaksin, ei rakennetta: sinun tehtäväsi on määrittää avaimet ja niiden tyypit.
# JSON-tila — kehotteen TÄYTYY kuvata rakenne
messages = [
{
"role": "system",
"content": "Palauta JSON, jossa avaimet: name (merkkijono), age (luku), city (merkkijono)."
},
{"role": "user", "content": text}
]
Mukautetussa tilassa dokumentoi kenttäsi. Tarkka kuvaus on arvokkaampi kuin pitkä kehotus, ja se kulkee skeeman mukana molemmilla kielillä.
class Product(BaseModel):
name: str = Field(description="Kaupallinen tuotenimi")
price: float = Field(description="Hinta EUR ilman alv, pyöristetty kahteen desimaaliin")
const ProductSchema = z.object({
name: z.string().describe("Kaupallinen tuotenimi"),
price: z.number().describe("Hinta EUR ilman alv, pyöristetty kahteen desimaaliin"),
});
Erota konteksti sisällöstä. Ohjeet kuuluvat järjestelmäviestiin, käsiteltävä data käyttäjäviestiin – ei koskaan päinvastoin, tai malli sekoittaa ohjeet lähdetekstiin.
messages = [
{"role": "system", "content": "Olet tiedonpoimija. [Muotoiluohjeet]"},
{"role": "user", "content": "[Käsiteltävä teksti — EI muotoiluohjeita tähän]"}
]
Seuraavat kaksi sääntöä koskevat turvaverkkoasi. Toteuta uudelleenyritysmekanismi: älä koskaan tee yhtäkään kutsua ilman varasuunnitelmaa; uudelleenyritys palautteen kanssa on tuotannon minimimalli. Ja validoi skeeman lisäksi, sillä skeema takaa rakenteen, kun taas semanttinen validointi – rajat, johdonmukaisuus, liiketoimintalogiikka – on sinun vastuullasi.
Viimeiset kolme liittyvät orkestrointiin. Valitse oikea malli oikeaan käyttötarkoitukseen: mistral-large-latest monimutkaisiin tehtäviin ja monikenttäiseen poimintaan, mistral-small-latest yksinkertaiseen luokitteluun ja peruspoimintaan, ministral-8b-latest suuriin taajuuksiin ja minimaaliseen viiveeseen. Kirjaa jokainen kutsu tuotannossa, tallentaen käytetyn mallin, keston, finish_reason-arvon ja lopputuloksen: ilman lokeja olet sokea. Lopuksi, älä optimoi kehotetta liian aikaisin – aloita yksinkertaisesti, mittaa, iteroidu; ennenaikainen kehotteiden optimointi on yleinen ansa, kun taas skeema ja validointi ovat todellisia vipuvarsia.
Kolme kallista sudenkuoppaa
Ensimmäinen on liian pieni max_tokens-arvo. JSON typistyy pitkissä vastauksissa, ja virhe ilmenee vasta suurilla dokumenteilla, usein vasta tuotantoon siirtymisen jälkeen.
# Vaarallinen — JSON typistyy pitkissä vastauksissa
response = client.chat.parse(
model="mistral-large-latest",
messages=messages,
response_format=MonSchema,
max_tokens=128 # Liian pieni monimutkaiselle skeemalle
)
Aseta max_tokens odotetun tulosteen koon perusteella: 20 rivin lasku vaatii enemmän tokeneita kuin yksinkertainen luokittelu.
Toinen on nollasta poikkeava lämpötila, joka tekee tuloksistasi toistamattomia ilman mitään hyötyä poimintatehtävässä.
# Vaarallinen tuotannossa — ei-toistettavat tulokset
response = client.chat.parse(
...,
temperature=0.7 # Tarpeeton vaihtelu poiminnassa
)
Kolmas on refleksi käyttää yhtä ainoaa mallia. Älä käytä mistral-large-mallia kaikkeen: binäärinen luokittelu ei vaadi tehokkainta mallia, ja ministral-8b hoitaa työn 5 kertaa nopeammin pienemmillä kustannuksilla.
Mitä seurata
Neljä mittaria kertovat putkistosi terveydestä. Onnistumisaste mittaa niiden kutsujen prosenttiosuuden, jotka palauttavat kelvollisen objektin ensimmäisellä yrityksellä; uudelleenyritysaste niiden kutsujen prosenttiosuuden, jotka tarvitsivat toisen mahdollisuuden. P50/P95-viive antaa mediaanivasteajan ja 95. persentiilin, joka on paljastavampi kuin keskiarvo. Kustannus poimintaa kohden, ilmaistuna kutsua kohden kulutettuina tokeneina, pitää laskun kurissa.
Näiden mittareiden osalta muutamat hälytyskynnykset pitävät paikkansa: alle 95 %:n onnistumisaste oikeuttaa keltaisen hälytyksen, alle 85 % punaisen; yli 10 sekunnin P95-viive vaatii selvitystä; ja avoin katkaisija (circuit breaker) vaatii välittömän hälytyksen.
Syventäminen
Neljä suuntaa laajentaa tätä kurssia luontevasti. Funktion kutsuminen käyttää strukturoituja tulosteita syöttämään funktiokutsuja agentissa. Striimaus mahdollistaa strukturoidun tulosteen vastaanottamisen vähitellen, mikä on tärkeää pitkissä vastauksissa. Hienosäätö säätää Mistral-mallia parantaakseen poiminnan laatua erityisessä datassasi. Arviointi puolestaan tarkoittaa automaattisen kehyksen pystyttämistä kultaisen datasetin ja mittareiden perusteella – tämä kertoo, parantaako kehotteen muutos todella asioita.
Täydellinen putkisto
Seuraava koodi kokoaa kurssin käytännöt yhdeksi kokonaisuudeksi: kenttä kerrallaan kuvattu skeema, validoija, joka hylkää rajojen ulkopuolelle jäävät pisteet, tehtävään mitoitettu malli, temperature=0, eksplisiittinen max_tokens, finish_reason-arvon tarkistus ja lokitus molemmille mahdollisille lopputuloksille.
from mistralai.client import Mistral
from pydantic import BaseModel, Field, field_validator
import logging
import time
logger = logging.getLogger("pipeline")
class CustomerFeedback(BaseModel):
sentiment: str = Field(description="positive, negative, or neutral")
score: float = Field(description="Score between -1.0 and 1.0")
category: str = Field(description="product, service, delivery, price, or other")
action_required: bool = Field(description="True if action is required")
summary: str = Field(description="One-sentence summary")
@field_validator("score")
@classmethod
def score_in_range(cls, v):
if not -1.0 <= v <= 1.0:
raise ValueError(f"Score out of bounds: {v}")
return v
def analyze_feedback(client: Mistral, text: str) -> CustomerFeedback:
start = time.time()
try:
response = client.chat.parse(
model="mistral-small-latest",
messages=[
{"role": "system", "content": "Analyze customer feedback."},
{"role": "user", "content": text}
],
response_format=CustomerFeedback,
temperature=0,
max_tokens=256
)
assert response.choices[0].finish_reason == "stop"
result = response.choices[0].message.parsed
logger.info(f"OK in {time.time()-start:.2f}s — {result.sentiment} ({result.score:+.1f})")
return result
except Exception as e:
logger.error(f"ERROR in {time.time()-start:.2f}s — {e}")
raise
Noin kolmekymmentä riviä, ja sinulla on komponentti, joka voidaan liittää turvallisesti järjestelmän ytimeen: juuri tämä on sitä, mitä strukturoidut tulosteet mahdollistavat.
Keskeiset asiat
- Käytä mukautettuja strukturoituja tulosteita tuotannossa, JSON-tilaa prototyyppaukseen
temperature=0,finish_reason-arvon tarkistus ja uudelleenyritys ovat ehdottomia- Valitse malli tehtävän monimutkaisuuden ja budjetin perusteella
- Seuraa onnistumisastetta, viivettä ja kustannuksia
- Aloita yksinkertaisesti, mittaa ja optimoi sitten
Testaa tietämyksesi
JSON-tila, skeemat, uudelleenyritys: strukturoitu tuloste hallinnassa?
1. JSON-tila vs mukautetut strukturoidut tulosteet: mikä on ero?
Vastaus: JSON-tila takaa syntaktisesti kelvollisen JSONin; mukautetut strukturoidut tulosteet valvovat lisäksi tarkkaa skeemaasi – kentät, tyypit, rakenne: täydellinen sopimus.
2. Mitä client.chat.parse() tarjoaa Pydanticin kanssa?
Vastaus: Täyden silmukan: Pydantic-skeema määrittelee rakenteen, API rajoittaa generointia, ja vastaus saapuu jo validoituna ja tyypitettynä Python-objektina – ei manuaalista jäsennystä.
3. Entä TypeScriptin puolella?
Vastaus: Sama mukavuus Zodin kanssa: Zod-skeema määrittelee ja validoi rakenteen – yksi totuuden lähde generoinnille ja tyypitykselle.
4. Mitä tehdä, kun tuloste ei noudata skeemaa?
Vastaus: Validoi systemaattisesti ja suunnittele uudelleenyritysstrategia: pyydä uudelleen virhe kontekstissa tai heikennä toimintaa hallitusti – älä koskaan luota sokeasti tulosteeseen.
5. Milloin strukturoitu tuloste on välttämätön?
Vastaus: Heti, kun ohjelma kuluttaa vastauksen ilman ihmisen tarkastusta: poiminta, integraatiot, putkistot – muodosta tulee kohteliaisuuden sijaan rajapinta.
Määritelty skeema, rajoitettu generointi, tulosteen validointi: kolmikko, joka tekee tekoälyn liitettäväksi oikeaan ohjelmistoon.