Dea-chleachtais Táirgeachta
Ar an leathanach seo
Ó Chruthúnas Coincheapa go dtí Imscaradh
Tá gach paraiméadar den API Chat Completions faoi do smacht anois. Is é an chuid is deacra fós: an bhearna a líonadh idir nótaibh oibre atá ag feidhmiú agus seirbhís a úsáideann daoine eile gan do rannpháirtíocht. Déanann an ceacht deireanach seo comhdhlúthú ar an gcúrsa iomlán i seicliosta táirgeachta inghníomhaithe, agus ansin léiríonn sé an bealach chuig cúrsaí leantacha.
Fíordheimhniú agus Leaganú Samhlacha
Tagann dhá chinneadh roimh an gcéad líne de loighic gnó. Baineann an chéad cheann leis an eochair API: fanann sí in athróg timpeallachta, riamh sa chód, agus is fearr dearbhú tosaithe ná None a scaipeann trí shraitheanna síos go teachtaireacht earráide dofhuaithe. Pleanáil rothlú freisin—cruthaigh an eochair nua, imscar í, ansin tarraing siar an sean-cheann, san ord sin, más mian leat seachaint ar an tseirbhís a chur as oifig.
import os
# I GCÓNAÍ: Eochair API in athróg timpeallachta
api_key = os.getenv("MISTRAL_API_KEY")
assert api_key, "MISTRAL_API_KEY gan sainiú"
# RIAMH: Eochair chrua-chódaithe sa chód
# api_key = "sk-abc123..." # TOIRMISCTE i dtáirgeadh
# I GCÓNAÍ: Rothlú rialta eochracha
# Cruthaigh eochair nua, imscar í, ansin tarraing siar an sean-cheann
Baineann an dara cinneadh leis an aitheantóir samhla. I bhforbairt, tugann -latest feabhsuithe duit gan iarracht. I dtáirgeadh, ciallaíonn an t-ainmniú céanna gur féidir le hathrú leagain ar thaobh an tsoláthraí iompar d’iarratais a athrú gan rabhadh, ar maidin Dé Máirt, gan aon rian gealltanais chun é a mhíniú. Pin an leagan.
# FORBAIRT — an leagan is déanaí
model = "mistral-large-latest"
# TÁIRGEADH — leagan seasta le haghaidh in-atáirgtheachta
model = "mistral-large-2512"
# Cén fáth? D'fhéadfadh athrú "latest" iompar d'iarratais a athrú
# gan rabhadh.
Cliant a Láimhseálann Teagmhais
Ní é an glaoch API é croílár comhtháthaithe táirgeachta ach gach rud timpeall air. Cuireann an rang thíos trí fhreagracht le chéile i bpointe bottlenneck amháin: iarracht arís le cúlú easpónantúil ar 429anna, sos gairid ar earráidí freastalaí, agus éalú láithreach d’earráidí cliant nach ndéanfaidh aon iarracht arís a shocrú. Normalaíonn sé an freagra freisin ina fhoclóir cobhsaí—ábhar, finish_reason, úsáid, samhail, ID—ionas nach mbraitheann an chuid eile de do chód ar chruth cruinn an oibiachta a thugann an SDK ar ais. Is é an logger.warning ar ghearrthacha amháin a thugann údar leis an gcoimeádú: is é an t-aon bhealach chun a fháil amach go bhfuil socruithe max_tokens ró-theann sula dtuairiscíonn úsáideoirí é.
from mistralai.client import Mistral
from mistralai.client.errors import SDKError
import time
import logging
logger = logging.getLogger(__name__)
class MistralClient:
"""Cliant táirgeachta le hiarracht arís, teorainn ama, agus logáil."""
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,
}
# Foláirimh má tá an freagra gearrtha
if result["finish_reason"] == "length":
logger.warning(f"Freagra gearrtha — req_id={response.id}")
return result
except SDKError as e:
if e.status_code == 429:
wait = 2 ** attempt
logger.warning(f"Teorainn ráta, iarracht arís {attempt+1}/{self.max_retries} i {wait}s")
time.sleep(wait)
elif e.status_code >= 500:
logger.error(f"Earráid freastalaí {e.status_code}, iarracht arís {attempt+1}")
time.sleep(1)
else:
logger.error(f"Earráid cliant {e.status_code}: {e.message}")
raise
raise Exception(f"Theip tar éis {self.max_retries} iarracht")
Rianaigh Costais De réir Mar a Tharlaíonn Siad
Is polaitíocht í do thomhaltas a fháil amach ar an mbille míosúil nach féidir le roinnt foirne a cheadú. Scríobhann an rianaire thíos líne JSONL amháin in aghaidh an ghlao— stampa ama, samhail, tokení ionchuir agus aschuir, finish_reason, ID iarratais—agus coinníonn sé iomlán seisiúin ar féidir leat ceist a chur air ag am ar bith. Ní mionsonra é formáid JSONL: déanann sé comhiomlánú le haon uirlis anailíse gan céim pharsála, agus ligeann láithreacht an ID iarratais duit neamhghnáchas costais a cheangal le glaoch sonrach.
import json
from datetime import datetime, timezone
class CostTracker:
"""Rianú costais API i bhfíor-am."""
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"Seisiún — Leid: {self.session_tokens['prompt']:,} | "
f"Críochnú: {self.session_tokens['completion']:,} | "
f"Iomlán: {total:,} tokení"
)
Bailíochtaigh ag an Dá Cheann
Ní mhuiníneoidh feidhmchlár láidir ná an méid a théann isteach ná an méid a thagann amach. Ar ionchur, diúltaigh teachtaireachtaí folmha, cuir teorainn le fad ag 10,000 carachtar chun cosc a chur ar chóip-ghreamú mí-ádhara do bhille a chur i méid, agus bain carachtair rialaithe a chuireann isteach ar thokenú. Ar aschur, ná diúltaigh aon rud ach ardaigh foláirimh: freagra a d’fhéadfadh a bheith gearrtha, freagra atá an-ghearr faoi bhun cúig charachtar, freagra atá an-fhada thar 50,000. Ghabhann na trí chomhartha seo an chuid is mó de theipeanna ciúine.
def validate_input(user_message: str) -> str:
"""Bailíochtaigh agus glan ionchur úsáideora."""
if not user_message or not user_message.strip():
raise ValueError("Teachtaireacht fholmh")
if len(user_message) > 10_000:
raise ValueError("Teachtaireacht ró-fhada (uas 10,000 carachtar)")
# Glan carachtair rialaithe
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:
"""Bailíochtaigh aschur API."""
warnings = []
if finish_reason == "length":
warnings.append("D'fhéadfadh an freagra a bheith gearrtha")
if not content or len(content.strip()) < 5:
warnings.append("Freagra an-ghearr go mínormálta")
if len(content) > 50_000:
warnings.append("Freagra an-fhada go mínormálta")
return {"content": content, "warnings": warnings, "valid": len(warnings) == 0}
Coinnigh an Fhuinneog Comhthéacs
Fadhb amháin eile: an drift mall de chomhráite fada. Meastann an fheidhm thíos toirt ag token amháin in aghaidh gach ceithre charachtar sa Fhraincis—neasúchán garbh ach leordhóthanach mar ghardráil—agus ligeann sí d’iarratais dul ar aghaidh fad is a fhanann siad faoi 80% den teorainn. Thairis sin, caomhnaíonn sí an leid córais agus baineann sí na teachtaireachtaí is sine amach go dtí go dtiteann siad ar ais faoi 70%. Tá an bhearna idir an dá thairseach seo d’aon turas: dá ngearrfá go dtí an tairseach spreagtha amháin, bhrúfadh sé an fheidhm ar ais sa dearg ar an gcéad teachtaireacht eile.
def manage_context(messages: list, max_tokens: int = 100_000) -> list:
"""Coinnigh teachtaireachtaí laistigh de theorainn tokení na samhla."""
# Meastachán: 1 token ~ 4 charachtar sa Fhraincis
total_chars = sum(len(m["content"]) for m in messages)
estimated_tokens = total_chars // 4
if estimated_tokens < max_tokens * 0.8:
return messages # Oireann gach rud
# Coinnigh córas + chéad agus last teachtaireachtaí
system = [m for m in messages if m["role"] == "system"]
history = [m for m in messages if m["role"] != "system"]
# Bain na teachtaireachtaí is sine
while estimated_tokens > max_tokens * 0.7 and len(history) > 2:
removed = history.pop(0)
estimated_tokens -= len(removed["content"]) // 4
return system + history
An Méid a Thógann Tú Ón gCúrsa Seo
Lean an turas ceithre chéim. Ar dtús, na bunús: an críochphointe, róil, paraiméadair bhunúsacha, agus struchtúr freagartha. Ina dhiaidh sin, sruthú, leis an bprótacal SSE, a chur i bhfeidhm i bPython, seichimh stoptha, agus cruasú trí safe_prompt agus gardaí. Ghabh leideanna an tríú céim—leideanna córais táirgeachta, cúpla sampla, struchtúrú XML agus Markdown, frith-phatrúin. Dún paraiméadair chasta an lúb: teocht agus Barr P go mion, pionóis láithreachta agus minicíochta, N críochnú, agus an seicliosta táirgeachta seo.
Déanann an chumraíocht thíos na roghanna seo a dhriogadh ina phointe tosaigh inchosanta d’imscaradh táirgeachta céad uair: leagan seasta, uasteorainn tokení oiriúnach don chás úsáide, teocht íseal le haghaidh comhsheasmhachta fíricí, top_p gan athrú ós rud é go ndéantar an teocht a choigeartú, pionóis neodrach mura dtugann riachtanas sonrach údar dóibh, agus safe_prompt cumasaithe.
# Cumraíocht tipiciúil d'iarratas táirgeachta
PRODUCTION_CONFIG = {
"model": "mistral-large-2512", # Leagan seasta
"max_tokens": 2000, # Oiriúnach don chás úsáide
"temperature": 0.3, # Comhsheasmhach agus fíriciúil
"top_p": 1.0, # Gan athrú má choigeartaítear an teocht
"presence_penalty": 0.0, # Réamhshocrú mura bhfuil riachtanas sonrach ann
"frequency_penalty": 0.0, # Réamhshocrú mura bhfuil riachtanas sonrach ann
"safe_prompt": True, # Sábháilteacht cumasaithe
}
Chun dul níos faide leis an API Mistral, leanann ceithre chúrsa chomhlántacha ar Corsen Academy:
- Leabaithe agus RAG — Cuardach seimeantach le
mistral-embedagus bunachair shonraí veicteoireacha - Glaoch Feidhme — Ceangail an tsamhail le do uirlisí agus APIanna seachtracha
- Míne-tiúnadh — Oiriúnaigh samhail do do réimse sonrach
- Táirgeadh agus Meastóireacht — Méadrachtaí, meastóireachtaí uathoibrithe, optamú costais
Príomhphointí
- Úsáid samhlacha leaganaithe i dtáirgeadh, riamh
-latest - Cuir iarracht arís + cúlú + logáil i bhfeidhm ón gcéad imscaradh
- Bailíochtaigh ionchuir AGUS aschuir gach glaoch API
- Rianaigh costais i bhfíor-am le rianaire tokení
- Bainistigh an fhuinneog comhthéacs le haghaidh comhráite fada
- Cumasigh
safe_promptmar líon sábháilteachta íosta - Déan tástáil ar do leideanna le cásanna imealla roimh gach scaoileadh táirgeachta
Tástáil do Chuid Eolais
Níl aon rúin fágtha sa chríochphointe chat/completions? Déanaimis seiceáil.
1. Cé na róil a struchtúraíonn an liosta teachtaireachtaí?
Freagra: córas (an fráma), úsáideoir (iarratais), cúntóir (freagraí na samhla)—tosaíonn an stair iomlán arís le gach glao, toisc go bhfuil an API gan staid.
2. Cad a fhaigheann tú sa réimse úsáide den fhreagra?
Freagra: Tokení a tomhailteadh ar ionchur agus ar aschur—bonn na billeála agus an mhéadrach le faire le haghaidh méadaithe agus costais.
3. Conas a oibríonn sruthú SSE?
Freagra: Tagann an freagra mar Imeachtaí arna Seoladh ag an bhFreastalaí (Server-Sent Events), blúire ar bhlúire: taispeánann tú de réir mar a thagann sé agus comhcheanglaíonn tú chun an teachtaireacht dheiridh a fháil.
4. Cad iad na seichimh stoptha?
Freagra: Chun giniúint a ghearradh chomh luath agus a fheictear teaghrán ar leith: rialaigh fad, stop ag teorainneoir, ráthaigh formáidí glana.
5. Teocht, Barr P, pionóis: cén úsáid i dtáirgeadh?
Freagra: Socraíonn Teocht/Barr P cinnteacht in aghaidh na tasc; teorannaíonn pionóis láithreachta/minicíochta athrá—socruithe le socrú in aghaidh an cháis úsáide agus le doiciméadú in éineacht le do leideanna.
Róil, úsáid, sruthú, stopanna, tiúnadh: fanann na bunúis daingean—cuireann na dea-chleachtais táirgeachta thuas in ord iad.