Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Najboljše prakse in naslednji koraki

Lekcija 14 od 14 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Povzetek tečaja
  2. Zavarovanje ključev API
  3. Obravnava napak
  4. Življenje z omejitvami hitrosti
  5. Nadzor stroškov
  6. Opazovanje dogajanja
  7. Kaj sledi
  8. Ključne ugotovitve
  9. Preveri svoje znanje

Povzetek tečaja

Preučil si vse osnove uporabe API-ja Mistral: ustvarjanje računa, upravljanje ključev, izbiro naročniškega paketa, namestitev SDK-jev za Python in TypeScript, pretakanje podatkov (streaming), večkratna pogovorna srečanja, selitev med različicama V1 in V2 ter uvedbo na glavne ponudnike oblaka. Kar sledi, se ne nanaša več na učenje samega API-ja, temveč na razliko med skripto, ki deluje, in aplikacijo, ki zdrži v produkcijskem okolju.

Zavarovanje ključev API

To je najpogostejši vzrok za incidente v produkcijskem okolju, skoraj vedno iz istega razloga: ključ, vgrajen v kodo „samo za testiranje”, je nato pozabljen v commitu. Ključ API se nikoli ne sme pojaviti v izvorni kodi; pripada okoljski spremenljivki ali, še bolje, upravitelju skrivnosti, kot so AWS Secrets Manager, Azure Key Vault ali HashiCorp Vault.

Naslednji korak je ločevanje. Uporabi en ključ na okolje – razvoj, testiranje (staging), produkcija – da preprečiš, da bi spodleteli testi porabili kvoto tvoje žive storitve. Uporabi en ključ na aplikacijo, da omejiš obseg škode: če ključ uhaja, prekličeš le tistega za prizadeto aplikacijo. Načrtuj rotacijo vsakih 90 dni v produkciji in konfiguriraj opozorila v konzoli Mistral za nenormalno uporabo: ogrožen ključ se najprej kaže kot krivulja uporabe, ki brez razloga poskoči.

Obravnava napak

V produkciji lahko vsak klic API spodleti. Vprašanje ni, ali se bo to zgodilo, temveč kdaj. Štiri statusne kode pokrivajo večino primerov, s katerimi se boš srečal:

KodaPomenUkrep
401 UnauthorizedNeveljaven ali potekel ključ APIPreveri svojo okoljsko spremenljivko
429 Too Many RequestsDosežena omejitev hitrostiPoskusi znova z eksponentnim zamikom
500 Internal Server ErrorTežava na strani MistralaSamodejni ponovni poskus po nekaj sekundah
503 Service UnavailableZačasna preobremenitevPoskusi znova z zamikom

Razlika je pomembna: napake 401 nikoli ne popraviš s ponovnim poskusom; kriva je tvoja konfiguracija. Ostale tri so prehodne narave in pravilen odziv je ponovni poskus s postopoma daljšimi zamiki – ena sekunda, nato dve, nato štiri. Takojšnji ponovni poskus v zanki pri kodi 429 le poslabša zasičenost, ki jo doživljaš.

Tukaj je vzorec v Pythonu: največ trije poskusi, izjema se sproži, če zadnji poskus ne uspe, in čas čakanja se po vsaki napaki podvoji z uporabo 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)

Prevod v TypeScript sledi popolnoma isti logiki, razen da je čas čakanja izražen v milisekundah, premor pa je izveden z obljubo (promise) in 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));
    }
  }
}

Življenje z omejitvami hitrosti

Omejitve hitrosti ščitijo API pred zlorabami in logika ponovnih poskusov sama po sebi ni dovolj, da bi jih spoštovali: stvari popravi šele naknadno. Preveri svoje omejitve v konzoli Mistral – zahtevkov na sekundo, žetonov na minuto – nato uvedi dušenje (throttling) na strani odjemalca, da preprečiš njihovo preseganje. Odvečnih zahtevkov ne zavrzi, temveč jih postavi v čakalno vrsto: uporabnik raje počaka dve sekundi, kot da dobi napako.

Ko kljub tvojim najboljšim prizadevanjem pride do kode 429, odgovor vključuje glavo Retry-After, ki označuje, kdaj poskusiti znova; branje tega je bolje od ugibanja. In če tvoja legitimna uporaba dosledno presega omejitve paketa Scale, zahtevaj povečanje kvote prek podpore, namesto da množiš obhodne rešitve.

Nadzor stroškov

Prva in daleč najučinkovitejša vzvod je izbira modela. Razvrščanje, ekstrakcija polj ali preoblikovanje besedila ne zahtevata zapletenega sklepanja: mistral-small-latest to opravi zelo dobro. mistral-large-latest prihrani za naloge, kjer kakovost sklepanja naredi razliko – analiza, kompleksna sinteza, pisanje daljših besedil – za generiranje kode pa uporabi codestral-latest. Ne plačuj za Mistral Large 3, da bi opravljal delo, ki ga Mistral Small opravi enako dobro: pri produkcijskih količinah se razlika meri v redih velikosti.

Drugi vzvod se nanaša na število izmenjanih žetonov. Jedrnat poziv, očiščen odvečnih navodil, nakopičenih skozi iteracije, stane manj pri vsakem klicu. Pri večkratnih pogovorih pošlji le potrebna sporočila: ponavljanje zgodovine tridesetih izmenjav za vsako vprašanje zelo hitro dvigne račun. Prilagodi max_tokens temu, kar dejansko pričakuješ, in predpomni pogoste odgovore – najcenejši zahtevek je tisti, ki ga ne opraviš.

Opazovanje dogajanja

V produkciji beleži vsak klic. Brez tega ne boš vedel, zakaj je bil odgovor okrnjen ali katera uporaba pojasnjuje mesečni račun. Spodnja funkcija ovije klic z dvema sledema: kaj odide in kaj pride nazaj, vključno s skupnim številom žetonov in razlogom za zaustavitev.

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

Ti dve vrstici odgovorita na večino vprašanj, ki si jih boš kasneje zastavil. finish_reason, ki signalizira omejitev dolžine, pojasni odgovor, prekinjen sredi stavka; drseče povprečno število žetonov razkriva poziv, ki je zrasel, ali zgodovino, ki ni bila pravilno očiščena.

Kaj sledi

Ko so osnove postavljene, se odpre več poti. Klicanje funkcij omogoča modelu, da kliče tvoje lastne funkcije in API-je. RAG (Retrieval-Augmented Generation) obogati odgovore s tvojimi internimi podatki, medtem ko vdelave (embeddings), ki pretvarjajo besedilo v vektorje, tvorijo gradnik semantičnega iskanja. Fino uglaševanje prilagodi model tvoji domeni, ko poziviranje ni več dovolj, agenti povezujejo klice za gradnjo avtonomnih sistemov, evalvacija pa ti daje način merjenja kakovosti odgovorov namesto ocenjevanja „na oko”.

Vsaka od teh tem ima v katalogu Corsen Academy namenjen tečaj.

Ključne ugotovitve

  • Zavaruj svoje ključe API z upraviteljem skrivnosti in redno rotacijo
  • Sistematično uvedi ponovni poskus z eksponentnim zamikom
  • Izberi najlažji model, ki zmore opraviti tvojo nalogo
  • Beleži vsak klic API za diagnostiko in optimizacijo stroškov
  • API Mistral je tvoja temeljna podlaga – naslednji koraki (klicanje funkcij, RAG, agenti) gradijo na vsem, kar si se naučil

Preveri svoje znanje

Konzola, SDK, ponudniki oblaka: ali je temelj API-ja postavljen?

1. Kakšni refleksi bi te morali voditi glede ključa API takoj, ko je ustvarjen?

Odgovor: Varno ga shrani (prikazan je le enkrat), ga obdrži izven kode prek okoljskih spremenljivk, uporabi en ključ na okolje in ga rotiraj, če imaš dvome.

2. Kaj razlikuje paketa Experiment in Scale?

Odgovor: Kvote in cene: Experiment za odkrivanje in prototipiranje, Scale za produkcijo – pred določanjem obsega preveri svoje omejitve v konzoli.

3. Kaj je ogrodje prvega klica v Pythonu?

Odgovor: Odjemalec, inicializiran s ključem, klic klepeta z modelom in seznamom sporočil, branje vsebine odgovora – pretakanje (streaming) je omogočeno za postopni prikaz.

4. Kako obravnavaš večkratni pogovor prek API-ja?

Odgovor: Tako, da zgodovino vzdržuješ sam: vsak zahtevek pošlje celoten seznam sporočil (uporabnik in asistent) – API je brez stanja.

5. Kaj moraš vedeti o uvedbah prek Azure, Vertex ali Bedrock?

Odgovor: Modeli Mistral so tam na voljo z avtentikacijo in obračunavanjem izbranega oblaka – ista družina modelov, drugačna dostopna točka, uporabno za infrastrukturne omejitve.

Ključ zavarovan, zgodovina upravljana, paket prilagojen: končne najboljše prakse to podlago preoblikujejo v produkcijsko bazo.