Najbolje prakse i sljedeći koraci
Na ovoj stranici
Sažetak tečaja
Prošao/la si sve osnove korištenja Mistral API-ja: izradu računa, upravljanje ključevima, odabir plana, instalaciju Python i TypeScript SDK-ova, streaming, višestruke razgovore, migraciju s V1 na V2 te implementaciju na glavnim pružateljima oblaka. Ono što slijedi više se ne tiče učenja samog API-ja, već razlike između skripte koja radi i aplikacije koja izdržava u produkcijskom okruženju.
Osiguravanje tvojih API ključeva
Ovo je najčešći uzrok incidenata u produkciji, gotovo uvijek iz istog razloga: ključ hardkodiran „samo za testiranje“, a zatim zaboravljen u commitu. API ključ nikada ne smije biti u izvornom kodu; pripada u varijablu okruženja ili, još bolje, u upravitelja tajnama poput AWS Secrets Managera, Azure Key Vaulta ili HashiCorp Vaulta.
Sljedeći korak je odvajanje. Koristi jedan ključ po okruženju – razvoj, testiranje, produkcija – kako bi spriječio/la da neuspjeli test potroši tvoju kvotu za živo uslugu. Koristi jedan ključ po aplikaciji kako bi ograničio/la štetu: ako ključ curi, opozivaš samo onaj za pogođenu aplikaciju. Planiraj rotaciju svakih 90 dana u produkciji i konfiguriraj upozorenja u Mistral konzoli za nenormalnu uporabu: kompromitirani ključ prvo se očituje kao krivulja uporabe koja naglo raste bez razloga.
Rukovanje greškama
U produkciji svaki poziv API-ju može failati. Pitanje nije hoće li se to dogoditi, već kada. Četiri statusna koda pokrivaju većinu onoga s čime ćeš se susresti:
| Kod | Značenje | Radnja |
|---|---|---|
| 401 Unauthorized | Nevažeći ili istekli API ključ | Provjeri svoju varijablu okruženja |
| 429 Too Many Requests | Dosegnuto ograničenje stope | Ponovi pokušaj s eksponencijalnim kašnjenjem |
| 500 Internal Server Error | Problem na strani Mistrala | Automatski ponovi pokušaj nakon nekoliko sekundi |
| 503 Service Unavailable | Privremeno preopterećenje | Ponovi pokušaj s kašnjenjem |
Razlika je bitna: nikada ne rješavaš 401 ponavljanjem pokušaja; tvoja konfiguracija je kriva. Ostala tri su prolazna, a ispravan odgovor je ponoviti pokušaj s progresivno dužim kašnjenjima – jedna sekunda, zatim dvije, zatim četiri. Ponavljanje pokušaja odmah u petlji kod 429 samo pogoršava zasićenje s kojim se suočavaš.
Evo obrasca u Pythonu: najviše tri pokušaja, proslijedi iznimku ako zadnji ne uspije i udvostruči vrijeme čekanja nakon svakog neuspjeha koristeći 2 ** attempt.
import time
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
def call_with_retry(messages, max_retries=3):
for attempt in range(max_retries):
try:
response = client.chat.complete(
model="mistral-small-latest",
messages=messages,
)
return response
except Exception as e:
if attempt == max_retries - 1:
raise
waitTime = 2 ** attempt # 1s, 2s, 4s
print(f"Error: {e}. Retrying in {waitTime}s...")
time.sleep(waitTime)
TypeScript verzija slijedi točno istu logiku, osim što je vrijeme čekanja izraženo u milisekundama, a pauza se gradi s promiseom i setTimeout:
async function callWithRetry(
client: Mistral,
messages: Array<{ role: string; content: string }>,
maxRetries = 3
) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await client.chat.complete({
model: 'mistral-small-latest',
messages,
});
} catch (error) {
if (attempt === maxRetries - 1) throw error;
const waitTime = Math.pow(2, attempt) * 1000;
console.log(`Error. Retrying in ${waitTime}ms...`);
await new Promise((r) => setTimeout(r, waitTime));
}
}
}
Život s ograničenjima stope (Rate Limits)
Ograničenja stope štite API od zlouporabe, a sama logika ponavljanja nije dovoljna da ih se poštuje: ona samo popravlja stvari nakon činjenice. Provjeri svoja ograničenja u Mistral konzoli – zahtjeva u sekundi, tokena u minuti – zatim implementiraj prigušivanje na strani klijenta kako bi spriječio/la njihovo premašivanje. Višak zahtjeva treba staviti u red čekanja, a ne odbaciti: korisnik radije čeka dvije sekunde nego dobiva grešku.
Kada se 429 dogodi unatoč tvojim najboljim naporima, odgovor uključuje zaglavlje Retry-After koje označava kada ponoviti pokušaj; čitanje toga bolje je od nagađanja. A ako tvoja legitimna uporaba dosljedno premašuje ograničenja Scale plana, zatraži povećanje kvote putem podrške umjesto množenja zaobilaznih rješenja.
Kontrola troškova
Prva poluga, i daleko najučinkovitija, je odabir modela. Klasifikacija, ekstrakcija polja ili preformuliranje ne zahtijevaju elaborirano rezoniranje: mistral-small-latest to obrađuje vrlo dobro. Rezerviraj mistral-large-latest za zadatke gdje kvaliteta rezoniranja čini razliku – analiza, složena sinteza, pisanje dugih formi – i koristi codestral-latest za generiranje koda. Ne plaćaj Mistral Large 3 da radi ono što Mistral Small može jednako dobro: u produkcijskom obujmu, razlika se mjeri redovima veličine.
Druga poluga tiče se broja razmijenjenih tokena. Sažet prompt, očišćen od suvišnih uputa nakupljenih tijekom iteracija, košta manje pri svakom pozivu. U višestrukim razgovorima šalji samo potrebne poruke: ponovno slanje povijesti od trideset razmjena za svako pitanje vrlo brzo diže račun. Prilagodi max_tokens onome što stvarno očekuješ i keširaj ponavljajuće odgovore – najjeftiniji zahtjev je onaj koji ne napraviš.
Promatranje onoga što se događa
U produkciji bilježi svaki poziv. Bez toga nećeš znati zašto je odgovor odsječen ili koja uporaba objašnjava mjesečni račun. Funkcija u nastavku omata poziv s dva traga: što izlazi, a zatim što dolazi, uključujući ukupan broj tokena i razlog zaustavljanja.
import logging
logger = logging.getLogger("mistral")
def logged_call(client, messages, model="mistral-small-latest"):
logger.info(f"API Call — model: {model}, messages: {len(messages)}")
response = client.chat.complete(model=model, messages=messages)
logger.info(
f"Response — tokens: {response.usage.total_tokens}, "
f"finish: {response.choices[0].finish_reason}"
)
return response
Ova dva retka odgovaraju na većinu pitanja koja ćeš si kasnije postavljati. finish_reason koji signalizira ograničenje duljine objašnjava odgovor odsječen usred rečenice; promjenjiv prosječan broj tokena otkriva prompt koji je narastao ili povijest koja nije ispravno očišćena.
Što dalje
S postavljenim osnovama otvaraju se nekoliko putova. Pozivanje funkcija omogućuje modelu da poziva tvoje vlastite funkcije i API-je. RAG (Retrieval-Augmented Generation) obogaćuje odgovore tvojim internim podacima, dok embeddingi, koji pretvaraju tekst u vektore, čine gradivni blok semantičkog pretraživanja. Fino podešavanje (fine-tuning) prilagođava model tvojoj domeni kada promptanje više nije dovoljno, agenti lančaju pozive za izgradnju autonomnih sustava, a evaluacija ti daje način mjerenja kvalitete odgovora umjesto procjene okom.
Svaka od ovih tema ima namjenske tečajeve u katalogu Corsen Academy.
Ključne točke
- Osiguraj svoje API ključeve upraviteljem tajnama i redovitom rotacijom
- Sustavno implementiraj ponavljanje s eksponencijalnim kašnjenjem
- Odaberi najlakši model sposoban obaviti tvoj zadatak
- Bilježi svaki poziv API-ju radi dijagnostike i optimizacije troškova
- Mistral API je tvoja temeljna osnova – sljedeći koraci (pozivanje funkcija, RAG, agenti) grade se na svemu što si naučio/la
Provjeri svoje znanje
Konzola, SDK, pružatelji oblaka: je li temelj API-ja postavljen?
1. Koje reflekse trebaš imati za API ključ čim bude stvoren?
Odgovor: Sigurno ga pohrani (prikazuje se samo jednom), drži ga izvan koda putem varijabli okruženja, koristi jedan ključ po okruženju i rotiraj ga ako sumnjaš.
2. Što razlikuje Experiment i Scale planove?
Odgovor: Kvote i cijene: Experiment za otkrivanje i prototipiranje, Scale za produkciju – provjeri svoja ograničenja u konzoli prije dimenzioniranja.
3. Koji je kostur prvog Python poziva?
Odgovor: Klijent inicijaliziran s ključem, poziv chata s modelom i popisom poruka, čitanje sadržaja odgovora – a streaming je omogućen za progresivni prikaz.
4. Kako rukuješ višestrukim razgovorom putem API-ja?
Odgovor: Održavanjem povijesti samostalno: svaki zahtjev šalje cijeli popis poruka (korisnik i asistent) – API je bez stanja (stateless).
5. Što trebaš znati o implementacijama putem Azurea, Vertexa ili Bedrocka?
Odgovor: Mistral modeli su tamo dostupni s autentifikacijom i naplatom odabranog oblaka – ista obitelj modela, drugačija pristupna točka, korisno za infrastrukturna ograničenja.
Ključ osiguran, povijest upravljana, plan prilagođen: konačne najbolje prakse pretvaraju ovu osnovu u produkcijsku bazu.