Labākā prakse ražošanas vidē
Šajā lapā
No pierādījuma koncepta līdz izvēršanai
Tagad tu pārzini visus Chat Completions API parametrus. Sarežģītākā daļa vēl priekšā: pārvarēt plaisu starp darbojošos piezīmju grāmatiņu un servisu, ko citi izmanto bez tavas iejaukšanās. Šī noslēdzošā nodarbība apkopo visu kursu darbībā pielietojamā ražošanas kontrolsarakstā un norāda ceļu uz turpmākajiem kursiem.
Autentifikācija un modeļu versiju kontrole
Pirms pirmās biznesa loģikas rindiņas jāpieņem divi lēmumi. Pirmais attiecas uz API atslēgu: tai jābūt vides mainīgajā, nekad kodā, un starta apstiprinājums ir labāks par None, kas izplatās trīs līmeņus uz leju līdz nesaprotamam kļūdas ziņojumam. Plāno arī rotāciju — ja vēlies izvairīties no servisa dīkstāves, vispirms izveido jauno atslēgu, tad to izvieto un tikai pēc tam atsakies no vecās.
import os
# VIENMĒR: API atslēga vides mainīgajā
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY nav definēta"
# NEKAD: iekodēta atslēga kodā
# api_key = "sk-abc123..." # AIZLIEGTS ražošanas vidē
# VIENMĒR: regulāra atslēgu rotācija
# Izveido jaunu atslēgu, izvieto to, tad atsakies no vecās
Otrais lēmums attiecas uz modeļa identifikatoru. Izstrādes laikā -latest dod uzlabojumus bez piepūles. Ražošanas vidē tas pats alias nozīmē, ka versijas maiņa pakalpojumu sniedzēja pusē var mainīt tavas lietotnes darbību bez brīdinājuma, otrdienas rītā, bez neviena commit ieraksta, kas to izskaidrotu. Fiksē versiju.
# IZSTRĀDE — jaunākā versija
model = "mistral-large-latest"
# RAŽOŠANA — fiksēta versija reproducējamībai
model = "mistral-large-2512"
# Kāpēc? "latest" maiņa var mainīt tavas lietotnes darbību
# bez brīdinājuma.
Klients, kas apstrādā incidentus
Ražošanas integrācijas sirds nav API izsaukums, bet viss, kas to ieskauj. Tālāk redzamā klase apvieno trīs pienākumus vienā kontrolpunktā: atkārtotu mēģinājumu ar eksponenciālu pauzi pie 429 kļūdām, īsu pauzi servera kļūdu gadījumā un tūlītēju klienta kļūdu eskalāciju, ko neviens atkārtots mēģinājums neatrisinās. Tā arī normalizē atbildi stabilā vārdnīcā — saturs, finish_reason, lietojums, modelis, ID —, lai pārējais tavs kods vairs nebūtu atkarīgs no precīzā SDK atgrieztā objekta formāta. Viena pati logger.warning saīsinājumu gadījumā attaisno šo encapsulāciju: tas ir vienīgais veids, kā uzzināt, ka max_tokens iestatījums ir par zemu, pirms to ziņo lietotāji.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import time
import logging
logger = logging.getLogger(__name__)
class MistralClient:
"""Ražošanas klients ar atkārtotu mēģinājumu, noildzi un žurnālēšanu."""
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,
}
# Brīdinājums, ja atbilde saīsināta
if result["finish_reason"] == "length":
logger.warning(f"Atbilde saīsināta — req_id={response.id}")
return result
except SDKError as e:
if e.status_code == 429:
wait = 2 ** attempt
logger.warning(f"Ātruma ierobežojums, mēģinājums {attempt+1}/{self.max_retries} pēc {wait}s")
time.sleep(wait)
elif e.status_code >= 500:
logger.error(f"Servera kļūda {e.status_code}, mēģinājums {attempt+1}")
time.sleep(1)
else:
logger.error(f"Klienta kļūda {e.status_code}: {e.message}")
raise
raise Exception(f"Neizdevās pēc {self.max_retries} mēģinājumiem")
Izseko izmaksas reāllaikā
Uzzināt savu patēriņu no mēneša rēķina ir greznība, ko var atļauties maz komandu. Tālāk redzamais izsekotājs katram izsaukumam ieraksta vienu JSONL rindiņu — laika zīmogs, modelis, ievades un izvades tokeni, finish_reason, pieprasījuma ID — un uztur sesijas kopsummu, ko vari vaicāt jebkurā brīdī. JSONL formāts nav sīkums: tas ļauj agregēt datus ar jebkuru analītikas rīku bez parsēšanas solīša, un pieprasījuma ID klātbūtne ļauj saistīt izmaksu anomāliju ar konkrētu izsaukumu.
import json
from datetime import datetime, timezone
class CostTracker:
"""API izmaksu izsekošana reāllaikā."""
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"Sesija — Prompt: {self.session_tokens['prompt']:,} | "
f"Pabeigums: {self.session_tokens['completion']:,} | "
f"Kopā: {total:,} tokeni"
)
Validē abos galos
Stabila lietotne neuzticas nedz tam, kas ieiet, nedz tam, kas iznāk. Ievades pusē noraidi tukšus ziņojumus, ierobežo garumu līdz 10 000 rakstzīmēm, lai novērstu neveiksmīga kopēšanas-ielīmēšanas gadījuma radītu rēķina uzbriešanu, un noņem vadības rakstzīmes, kas traucē tokenizāciju. Izvades pusē neko noraidi, bet izsaki brīdinājumus: potenciāli saīsināta atbilde, neparasti īsa atbilde (mazāk par piecām rakstzīmēm), neparasti gara atbilde (vairāk par 50 000). Šie trīs signāli aptver lielāko daļu kluso kļūmju.
def validate_input(user_message: str) -> str:
"""Validē un attīra lietotāja ievadi."""
if not user_message or not user_message.strip():
raise ValueError("Tukšs ziņojums")
if len(user_message) > 10_000:
raise ValueError("Ziņojums pārāk garš (maks. 10 000 rakstzīmes)")
# Attīra vadības rakstzīmes
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:
"""Validē API izvadi."""
warnings = []
if finish_reason == "length":
warnings.append("Atbilde potenciāli saīsināta")
if not content or len(content.strip()) < 5:
warnings.append("Neparasti īsa atbilde")
if len(content) > 50_000:
warnings.append("Neparasti gara atbilde")
return {"content": content, "warnings": warnings, "valid": len(warnings) == 0}
Uzturi konteksta logu
Vēl viena problēma: lēnā ilgstošu sarunu novirzīšanās. Tālāk redzamā funkcija novērtē apjomu kā vienu tokeni uz četrām rakstzīmēm franču valodā — aptuvens tuvinājums, bet pietiekams kā drošības barjera — un ļauj pieprasījumiem iziet cauri, kamēr tie nepārsniedz 80% no limita. Pārsniedzot to, tā saglabā sistēmas uzvedni un noņem vecākos ziņojumus, līdz apjoms nokrītas zem 70%. Šī atstarpe starp abiem sliekšņiem ir apzināta: saīsināšana tikai līdz aktivizēšanas slieksnim liktu funkcijai nākamajā ziņojumā atkal nonākt sarkanajā zonā.
def manage_context(messages: list, max_tokens: int = 100_000) -> list:
"""Uztur ziņojumus modeļa tokena limita robežās."""
# Novērtējums: 1 tokens ~ 4 rakstzīmes franču valodā
total_chars = sum(len(m["content"]) for m in messages)
estimated_tokens = total_chars // 4
if estimated_tokens < max_tokens * 0.8:
return messages # Viss ietilpst
# Saglabā sistēmu + pirmos un pēdējos ziņojumus
system = [m for m in messages if m["role"] == "system"]
history = [m for m in messages if m["role"] != "system"]
# Noņem vecākos ziņojumus
while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
removed = history.pop(0)
estimated_tokens -= len(removed["content"]) // 4
return system + history
Ko tu paņem līdzi no šī kursa
Ceļojums sekoja četriem soļiem. Pirmkārt, pamati: beigu punkts, lomas, pamatparametri un atbildes struktūra. Tālāk straumēšana, izmantojot SSE protokolu, tā Python implementāciju, apturēšanas secības un nostiprināšanu ar safe_prompt un aizsargbarjerām. Trešo posmu aizņēma uzveidošana — ražošanas sistēmu uzvednes, few-shot, XML un Markdown strukturēšana, anti-paraugi. Izvērsti parametri noslēdza ciklu: temperatūra un Top P detalizēti, klātbūtnes un biežuma sodi, N pabeigumi un šis ražošanas kontrolsaraksts.
Tālāk redzamā konfigurācija apkopo šīs izvēles aizstāvamā sākumpunktā pirmajai izvēršanai ražošanas vidē: fiksēta versija, lietojumam piemērots tokena griests, zema temperatūra faktoloģiskai konsekvencei, top_p nemainīts, jo temperatūra ir pielāgota, neitrāli sodi, ja vien specifiska vajadzība tos neattaisno, un safe_prompt ieslēgts.
# Tipiska konfigurācija ražošanas lietotnei
PRODUCTION_CONFIG = {
"model": "mistral-large-2512", # Fiksēta versija
"max_tokens": 2000, # Pielāgots lietojumam
"temperature": 0.3, # Konsekvents un faktoloģisks
"top_p": 1.0, # Nemainīts, ja temperatūra pielāgota
"presence_penalty": 0.0, # Noklusējums, ja nav specifiskas vajadzības
"frequency_penalty": 0.0, # Noklusējums, ja nav specifiskas vajadzības
"safe_prompt": True, # Drošība ieslēgta
}
Lai dotos tālāk ar Mistral API, Corsen Academy piedāvā četrus papildu kursus:
- Embeddings un RAG — Semantiskā meklēšana ar
mistral-embedun vektoru datubāzēm - Funkciju izsaukšana — Savieno modeli ar saviem rīkiem un ārējiem API
- Smalkā noregulēšana — Pielāgo modeli savai specifiskajai jomai
- Ražošana un novērtēšana — Metrikas, automatizēti novērtējumi, izmaksu optimizācija
Galvenās atziņas
- Ražošanas vidē izmanto versijotus modeļus, nekad
-latest - Ievies atkārtotu mēģinājumu + pauzi + žurnālēšanu jau no pirmās izvēršanas
- Validē gan katras API izsaukuma ievades, gan izvades
- Izseko izmaksas reāllaikā ar tokena izsekotāju
- Pārvaldi konteksta logu ilgstošām sarunām
- Iespējo
safe_promptkā minimālu drošības tīklu - Pirms katras izvēršanas ražošanas vidē testē savas uzvednes ar robežgadījumiem
Pārbaudi savas zināšanas
Vairs nekādu noslēpumu chat/completions beigu punktā? Pārliecināsimies.
1. Kuras lomas strukturē ziņojumu sarakstu?
Atbilde: system (ietvars), user (pieprasījumi), assistant (modeļa atbildes) — pilna vēsture sākas no jauna ar katru izsaukumu, jo API ir bezstāvokļa.
2. Ko atrodi atbildes laukā usage?
Atbilde: Tokenus, kas patērēti ievadē un izvadē — rēķinu pamats un metrika, kas jāuzrauga, lai noteiktu izmērus un izmaksas.
3. Kā darbojas SSE straumēšana?
Atbilde: Atbilde pienāk kā Server-Sent Events, fragments pa fragmentam: tu to attēlo, kamēr tā nāk, un savieno, lai iegūtu galīgo ziņojumu.
4. Kam domātas apturēšanas secības?
Atbilde: Lai pārtrauktu ģenerēšanu, tiklīdz parādās noteikta virkne: kontrolē garumu, apstājas pie atdalītāja, garantē tīrus formātus.
5. Temperatūra, Top P, sodi: kāds pielietojums ražošanas vidē?
Atbilde: Temperatūra/Top P nosaka determinismu atkarībā no uzdevuma; klātbūtnes/biežuma sodi ierobežo atkārtošanos — iestatījumi, kas jāfiksē katram lietojumam un jādokumentē līdzās uzvednēm.
Lomas, lietojums, straumēšana, apturēšana, noregulēšana: pamati ir stabili — iepriekš minētā ražošanas labākā prakse tos sakārto.