Käytännöt tuotantoympäristöön
Tällä sivulla
Konseptista tuotantoon
Hallitset nyt kaikki Chat Completions -rajapinnan parametrit. Haastavin osuus on vielä edessä: kuilu toimivan muistikirjan ja palvelun välillä, jota muut käyttävät ilman väliintuloasi. Tämä viimeinen oppitunti tiivistää koko kurssin toimintakelpoiseksi tuotantotarkistuslistaksi ja osoittaa suunnan jatkokursseille.
Todennus ja malliversioinnit
Ennen ensimmäistä liiketoimintalogiikan riviä on tehtävä kaksi päätöstä. Ensimmäinen koskee API-avainta: sen tulee olla ympäristömuuttujassa, ei koskaan koodissa, ja käynnistyksen aikainen varmistus on parempi kuin None, joka etenee kolme tasoa alaspäin aiheuttaen käsittämättömän virheilmoituksen. Suunnittele myös kierto: luo uusi avain, ota se käyttöön ja peruuta vanha – tässä järjestyksessä, jos haluat välttää palvelun katkokset.
import os
# AINA: API-avain ympäristömuuttujassa
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY not defined"
# EI KOSKAAN: kovakoodattu avain koodissa
# api_key = "sk-abc123..." # KIELLETTY tuotannossa
# AINA: säännöllinen avainten kierto
# Luo uusi avain, ota se käyttöön, peruuta sitten vanha
Toinen päätös koskee mallitunnistetta. Kehitysvaiheessa -latest antaa parannuksia ilman vaivaa. Tuotannossa sama alias tarkoittaa, että tarjoajan puolella tapahtuva versiopäivitys voi muuttaa sovelluksesi toimintaa ilman varoitusta, keskellä tiistai-aamua, ilman commit-historiaan kirjattua selitystä. Lukitse versio.
# KEHITYS — uusin versio
model = "mistral-large-latest"
# TUOTANTO — kiinteä versio toistettavuuden vuoksi
model = "mistral-large-2512"
# Miksi? "latest"-muutos voi muuttaa sovelluksesi toimintaa
# ilman varoitusta.
Asiakasohjelma, joka hallitsee häiriötilanteet
Tuotantointegraation ydin ei ole API-kutsu itse, vaan kaikki sen ympärillä. Alla oleva luokka niputtaa kolme vastuuta yhteen tukikohtaan: uudelleenyritys eksponentiaalisella viiveellä 429-virheille, lyhyt tauko palvelinvirheillä ja asiakasvirheiden välitön eskalointi, joita mikään uudelleenyritys ei korjaa. Se myös normalisoi vastauksen vakaaksi sanakirjaksi – sisältö, finish_reason, käyttö, malli, ID – jotta loput koodistasi eivät enää riipu SDK:n palauttaman objektin tarkasta rakenteesta. Pelkkä logger.warning typistyksistä oikeuttaa kapseloinnin: se on ainoa tapa huomata, että max_tokens-asetus on liian tiukka, ennen kuin käyttäjät valittavat siitä.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import time
import logging
logger = logging.getLogger(__name__)
class MistralClient:
"""Tuotantoasiakas uudelleenyrityksillä, aikakatkaisulla ja lokituksella."""
def __init__(self, api_key: str, max_retries: int = 3):
self.client = Mistral(api_key=api_key)
self.max_retries = max_retries
def complete(self, messages: list, **kwargs) -> dict:
for attempt in range(self.max_retries):
try:
response = self.client.chat.complete(
messages=messages,
**kwargs
)
result = {
"content": response.choices[0].message.content,
"finish_reason": response.choices[0].finish_reason,
"usage": {
"prompt": response.usage.prompt_tokens,
"completion": response.usage.completion_tokens,
"total": response.usage.total_tokens,
},
"model": response.model,
"id": response.id,
}
# Hälytys, jos vastaus typistyi
if result["finish_reason"] == "length":
logger.warning(f"Response truncated — req_id={response.id}")
return result
except SDKError as e:
if e.status_code == 429:
wait = 2 ** attempt
logger.warning(f"Rate limit, retry {attempt+1}/{self.max_retries} in {wait}s")
time.sleep(wait)
elif e.status_code >= 500:
logger.error(f"Server error {e.status_code}, retry {attempt+1}")
time.sleep(1)
else:
logger.error(f"Client error {e.status_code}: {e.message}")
raise
raise Exception(f"Failed after {self.max_retries} attempts")
Seuraa kustannuksia reaaliajassa
Kulutuksen havaitseminen kuukausilaskulta on ylellisyyttä, jota harvat tiimit voivat sallia. Alla oleva seuranta kirjoittaa yhden JSONL-rivin kutakin kutsua kohti – aikaleima, malli, syöte- ja tulostetokenit, finish_reason, pyyntötunniste – ja ylläpitää istunnon kokonaissummaa, jonka voit kysyä milloin tahansa. JSONL-muoto ei ole yksityiskohta: se aggregoituu minkä tahansa analytiikkatyökalun kanssa ilman jäsentämisvaihetta, ja pyyntötunnisteen olemassaolo mahdollistaa kustannuspoikkeaman sidomisen tiettyyn kutsuun.
import json
from datetime import datetime, timezone
class CostTracker:
"""API-kustannusten reaaliaikainen seuranta."""
def __init__(self, log_path: str = "api_costs.jsonl"):
self.log_path = log_path
self.session_tokens = {"prompt": 0, "completion": 0}
def log(self, response_data: dict):
usage = response_data["usage"]
self.session_tokens["prompt"] += usage["prompt"]
self.session_tokens["completion"] += usage["completion"]
entry = {
"ts": datetime.now(timezone.utc).isoformat(),
"model": response_data["model"],
"prompt_tokens": usage["prompt"],
"completion_tokens": usage["completion"],
"finish_reason": response_data["finish_reason"],
"id": response_data["id"],
}
with open(self.log_path, "a") as f:
f.write(json.dumps(entry) + "\n")
def report(self) -> str:
total = self.session_tokens["prompt"] + self.session_tokens["completion"]
return (
f"Session — Prompt: {self.session_tokens['prompt']:,} | "
f"Completion: {self.session_tokens['completion']:,} | "
f"Total: {total:,} tokens"
)
Validoi molemmissa päissä
Vankka sovellus ei luota siihen, mitä menee sisään eikä siihen, mitä tulee ulos. Syötteessä hylkää tyhjät viestit, rajoita pituus 10 000 merkkiin estääksesi epäonnisen kopioi-liitä -operaation kasvattamasta laskuasi, ja poista ohjausmerkit, jotka häiritsevät tokenisointia. Tulosteessa älä hylkää mitään, mutta nosta varoituksia: mahdollisesti typistynyt vastaus, epänormaalisti lyhyt vastaus (alle 5 merkkiä), epänormaalisti pitkä vastaus (yli 50 000). Nämä kolme signaalia catches valtaosan hiljaisista virheistä.
def validate_input(user_message: str) -> str:
"""Validoi ja siivoa käyttäjän syöte."""
if not user_message or not user_message.strip():
raise ValueError("Empty message")
if len(user_message) > 10_000:
raise ValueError("Message too long (max 10,000 characters)")
# Siivoa ohjausmerkit
cleaned = "".join(c for c in user_message if c.isprintable() or c in "\n\t")
return cleaned.strip()
def validate_output(content: str, finish_reason: str) -> dict:
"""Validoi API:n tuloste."""
warnings = []
if finish_reason == "length":
warnings.append("Response potentially truncated")
if not content or len(content.strip()) < 5:
warnings.append("Abnormally short response")
if len(content) > 50_000:
warnings.append("Abnormally long response")
return {"content": content, "warnings": warnings, "valid": len(warnings) == 0}
Hallitse konteksti-ikkunaa
Viimeinen ongelma: pitkien keskustelujen hidas ajelehtiminen. Alla oleva funktio arvioi volyymin yhdeksi tokeniksi neljää merkkiä kohti ranskankielessä – karkea approksimaatio, mutta riittävä suojaksi – ja päästää pyynnöt läpi niin kauan kuin ne pysyvät alle 80 % rajasta. Sen yli se säilyttää järjestelmäkehotteen ja poistaa vanhimpia viestejä, kunnes määrä laskee alle 70 %. Tämä kuilu kahden kynnyksen välillä on tahallinen: leikkaaminen vain laukaisukynnykseen työntäisi funktion takaisin punaiselle seuraavassa viestissä.
def manage_context(messages: list, max_tokens: int = 100_000) -> list:
"""Pidä viestit mallin tokenrajoituksen sisällä."""
# Arvio: 1 token ~ 4 merkkiä ranskaksi
total_chars = sum(len(m["content"]) for m in messages)
estimated_tokens = total_chars // 4
if estimated_tokens < max_tokens * 0.8:
return messages # Kaikki mahtuu
# Säilytä järjestelmä + ensimmäinen ja viimeinen viesti
system = [m for m in messages if m["role"] == "system"]
history = [m for m in messages if m["role"] != "system"]
# Poista vanhimpia viestejä
while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
removed = history.pop(0)
estimated_tokens -= len(removed["content"]) // 4
return system + history
Mitä otit mukaan tästä kurssista
Matka eteni neljässä vaiheessa. Ensinnäkin perusteet: päätepiste, roolit, perusparametrit ja vastauksen rakenne. Seuraavaksi streamaus, jossa SSE-protokolla, sen Python-toteutus, lopetussekvenssit ja lujittaminen safe_prompt- ja guardrail-toiminnoilla. Kehotteet veivät kolmannen vaiheen – tuotantojärjestelmäkehotteet, few-shot, XML- ja Markdown-jäsennys, anti-mallit. Edistyneet parametrit päättivät kierroksen: lämpötila ja Top P yksityiskohtaisesti, läsnäolo- ja taajuussakot, N täydennystä ja tämä tuotantotarkistuslista.
Alla oleva konfiguraatio tiivistää nämä valinnat puolustettavaksi lähtökohdaksi ensimmäiseen tuotantoonottoon: kiinteä versio, käyttötarkoitukseen sopiva tokenkatto, matala lämpötila faktuaalista johdonmukaisuutta varten, top_p koskemattomana lämpötilan säädön vuoksi, neutraalit sakot ellei erityistarve perustele niitä, ja safe_prompt käytössä.
# Tyypillinen konfiguraatio tuotantosovellukselle
PRODUCTION_CONFIG = {
"model": "mistral-large-2512", # Kiinteä versio
"max_tokens": 2000, # Sopii käyttötarkoitukseen
"temperature": 0.3, # Johdonmukainen ja faktuaalinen
"top_p": 1.0, # Koskematon, jos lämpötilaa säädetään
"presence_penalty": 0.0, # Oletus, ellei erityistarvetta
"frequency_penalty": 0.0, # Oletus, ellei erityistarvetta
"safe_prompt": True, # Turvallisuus käytössä
}
Päästäksesi pidemmälle Mistral API:n kanssa, Corsen Academyssä seuraa neljä täydentävää kurssia:
- Upotukset ja RAG – Semanttinen haku
mistral-embed:llä ja vektoritietokannoilla - Funktio-kutsut – Yhdistä malli työkaluihisi ja ulkoisiin rajapintoihin
- Hienosäätö – Mukauta malli omaan toimialaasi
- Tuotanto ja arviointi – Mittarit, automatisoidut arvioinnit, kustannusten optimointi
Keskeiset asiat
- Käytä versioituja malleja tuotannossa, ei koskaan
-latest - Toteuta uudelleenyritys + viive + lokitus jo ensimmäisestä käyttöönotosta
- Validoi jokaisen API-kutsun sekä syötteet ETTÄ tulosteet
- Seuraa kustannuksia reaaliajassa token-seurannalla
- Hallitse konteksti-ikkunaa pitkissä keskusteluissa
- Ota
safe_promptkäyttöön vähimmäisturvaverkkona - Testaa kehotteesi reunatapauksilla ennen jokaista tuotantoon julkaisua
Testaa tietämyksesi
Eikö chat/completions-päätepisteessä ole enää salaisuuksia? Varmistetaan asia.
1. Mitkä roolit jäsentelevät viestiluetteloa?
Vastaus: system (kehys), user (pyynnöt), assistant (mallin vastaukset) – koko historia alkaa alusta jokaisella kutsulla, sillä API on tilaton.
2. Mitä löydät vastauksen usage-kentästä?
Vastaus: Syötteessä ja tulosteessa kulutetut tokenit – laskutuksen perusta ja mittari, jota tulee seurata mitoituksen ja kustannusten vuoksi.
3. Miten SSE-streamaus toimii?
Vastaus: Vastaus saapuu Server-Sent Events -muodossa, osana osalta: näytät sen saapuessa ja yhdistät osat saadaksesi lopullisen viestin.
4. Mihin lopetussekvenssejä käytetään?
Vastaus: Katkaisemaan generointi heti, kun annettu merkkijono ilmestyy: hallitse pituutta, pysähdy erottimeen, takaa siistit muodot.
5. Lämpötila, Top P, sakot: mikä käyttö tuotannossa?
Vastaus: Lämpötila/Top P asettavat determinismin tehtäväkohtaisesti; läsnäolo-/taajuussakot rajoittavat toistoa – asetukset, jotka tulee lukita käyttötapausta kohti ja dokumentoida kehotteidesi yhteyteen.
Roolit, käyttö, streamaus, lopetukset, viritys: perusteet pitävät – yllä olevat tuotantokäytännöt järjestävät ne oikein.