Parhaat käytännöt ja seuraavat askeleet
Tällä sivulla
Kurssin kertaus
Olet käynyt läpi kaikki Mistral API:n perusteet: tilin luominen, avainten hallinta, suunnitelman valinta, Python- ja TypeScript-SDK:iden asennus, suoratoisto, monivaiheiset keskustelut, V1/V2-migraatio ja käyttöönotto suurimmilla pilvipalveluntarjoajilla. Seuraavaksi ei enää opetella itse API:a, vaan siirrytään tarkastelemaan eroa toimivan skriptin ja tuotantokelpoisen sovelluksen välillä.
API-avainten suojaaminen
Tämä on yleisin tuotantotilanteiden syy, lähes aina samasta syystä: avain on kovakoodattu “vain testausta varten” ja unohdettu commitiin. API-avain ei saa koskaan esiintyä lähdekoodissa; sen kuuluu olla ympäristömuuttujassa tai, vielä parempi, salaisuuksien hallintajärjestelmässä kuten AWS Secrets Manager, Azure Key Vault tai HashiCorp Vault.
Seuraavaksi tulee erottelu. Käytä yhtä avainta kutakin ympäristöä kohden – kehitys, testaus, tuotanto – estääksesi epäonnistuneen testin kuluttamasta live-palvelusi kiintiötä. Käytä yhtä avainta kutakin sovellusta kohden rajoittaaksesi vahinkojen laajuutta: jos avain vuotaa, kumoat vain kyseisen sovelluksen avaimen. Suunnittele avainten kierrätys 90 päivän välein tuotannossa ja määritä hälytykset Mistral Consoleen epänormaalin käytön varalta: kompromissoitunut avain näkyy ensin käyttökäyränä, joka nousee ilman syytä.
Virheiden käsittely
Tuotannossa jokainen API-kutsu voi epäonnistua. Kysymys ei ole siinä, tapahtuuko se, vaan milloin. Neljä statuskoodia kattaa suurimman osan kohtaamistasi tilanteista:
| Koodi | Merkitys | Toimenpide |
|---|---|---|
| 401 Unauthorized | Virheellinen tai vanhentunut API-avain | Tarkista ympäristömuuttujasi |
| 429 Too Many Requests | Nopeusrajoitus saavutettu | Yritä uudelleen eksponentiaalisella viiveellä |
| 500 Internal Server Error | Ongelma Mistralin puolella | Automaattinen uudelleenyritys muutaman sekunnin kuluttua |
| 503 Service Unavailable | Väliaikainen ylikuormitus | Yritä uudelleen viiveellä |
Ero on tärkeä: et koskaan korjaa 401-virhettä yrittämällä uudelleen; vika on konfiguraatiossasi. Muut kolme ovat ohimeneviä, ja oikea vastaus on yrittää uudelleen progressively pitenevin viivein – yksi sekunti, sitten kaksi, sitten neljä. Uudelleenyritys välittömästi silmukassa 429-virheen sattuessa vain pahentaa kokemasi kyllästymisen.
Tässä on malli Pythonille: enintään kolme yritystä, poikkeuksen heittäminen, jos viimeinen epäonnistuu, ja odotusajan kaksinkertaistaminen jokaisen epäonnistumisen jälkeen käyttäen kaavaa 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-toteutus noudattaa täsmälleen samaa logiikkaa, paitsi että odotusaika ilmaistaan millisekunteina ja tauko toteutetaan promisen ja setTimeout-funktion avulla:
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));
}
}
}
Nopeusrajoitusten kanssa eläminen
Nopeusrajoitukset suojaavat API:a väärinkäytöltä, ja pelkkä uudelleenyrityslogiikka ei riitä niiden kunnioittamiseen: se korjaa asioita vasta jälkikäteen. Tarkista rajasi Mistral Consolessa – pyynnöt sekunnissa, tokenit minuutissa – ja toteuta sitten asiakaspuolen kuristus estääksesi niiden ylittämisen. Liialliset pyynnöt pitäisi laittaa jonoon, ei hylätä: käyttäjä mieluummin odottaa kaksi sekuntia kuin saa virheen.
Kun 429-virhe tapahtuu parhaista yrityksistäsi huolimatta, vastaus sisältää Retry-After-otsikon, joka ilmoittaa, milloin kannattaa yrittää uudelleen; sen lukeminen on parempaa kuin arvaaminen. Ja jos laillinen käyttösi ylittää jatkuvasti Scale-suunnitelman rajat, pyydä kiintiön korotusta tuen kautta sen sijaan, että moninkertaistaisit kiertotietä.
Kustannusten hallinta
Ensimmäinen ja ehdottomasti tehokkain vipu on mallin valinta. Luokittelu, kenttien poiminta tai uudelleenmuotoilu eivät vaadi monimutkaista päättelyä: mistral-small-latest hoitaa ne erinomaisesti. Varaa mistral-large-latest tehtäviin, joissa päättelyn laatu ratkaisee – analyysi, monimutkainen synteesi, pitkät tekstit – ja käytä codestral-latest koodin generointiin. Älä maksa Mistral Large 3:sta siitä, mihin Mistral Small pystyy yhtä hyvin: tuotantomäärissä ero mitataan suuruusluokissa.
Toinen vipu koskee vaihdettujen tokenien määrää. Tiivis kehote, josta on riisuttu iteratioiden aikana kertyneet redundanssit, maksaa vähemmän jokaisessa kutsussa. Monivaiheisissa keskusteluissa lähetä vain tarvittavat viestit: kolmenkymmenen vaihdon historian toistaminen jokaisen kysymyksen yhteydessä kasvattaa laskua hyvin nopeasti. Säädä max_tokens vastaamaan sitä, mitä todella odotat, ja välimuistita toistuvat vastaukset – halvin pyyntö on se, jota et tee.
Tapahtumien havainnointi
Tuotannossa kirjaista jokainen kutsu. Ilman tätä et tiedä, miksi vastaus katkesi tai mikä käyttö selittää kuukauden laskun. Alla oleva funktio käärii kutsun kahteen jäljitettävään tapahtumaan: mitä lähtee ulos ja mitä tulee takaisin, mukaan lukien tokenien kokonaismäärä ja pysäytyssyy.
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
Nämä kaksi riviä vastaavat useimpiin myöhemmin esittämiisi kysymyksiin. Pituusrajaa signaloiva finish_reason selittää keskeltä katkenneen vastauksen; drifting keskimääräinen tokenimäärä paljastaa kehotteen, joka on kasvanut, tai historian, jota ei ole tyhjennetty asianmukaisesti.
Mitä seuraavaksi
Kun perusteet ovat kunnossa, useita polkuja avautuu. Funktion kutsuminen mahdollistaa mallin kutsua omia funktioitasi ja API-rajapintojasi. RAG (Retrieval-Augmented Generation) rikastaa vastauksia sisäisillä tiedoillasi, kun taas upotukset (embeddings), jotka muuntavat tekstin vektoreiksi, muodostavat semanttisen haun perusrakennuspalikan. Hienosäätö mukauttaa mallin toimialaasi, kun kehotteet eivät enää riitä, agentit ketjuttavat kutsuja rakentaakseen autonomisia järjestelmiä, ja arviointi antaa tavan mitata vastauksen laatua sen sijaan, että arvioisit sitä silmämääräisesti.
Jokaisesta näistä aiheista on omat kurssinsa Corsen Academyn valikoimassa.
Keskeiset asiat
- Suojaa API-avaimesi salaisuuksien hallintajärjestelmällä ja säännöllisellä kierroksella
- Toteuta systemaattisesti uudelleenyritys eksponentiaalisella viiveellä
- Valitse tehtävääsi varten kevyin mahdollinen malli
- Kirjaa jokainen API-kutsu diagnostiikkaa ja kustannusten optimointia varten
- Mistral API on perustasi – seuraavat askeleet (funktion kutsuminen, RAG, agentit) rakentuvat kaiken oppimasi päälle
Testaa tietämyksesi
Console, SDK, pilvipalveluntarjoajat: onko API-perusta kunnossa?
1. Mitä refleksejä sinulla pitäisi olla API-avaimen suhteen heti sen luomisen jälkeen?
Vastaus: Tallenna se turvallisesti (se näytetään vain kerran), pidä se poissa koodista ympäristömuuttujien avulla, käytä yhtä avainta kutakin ympäristöä kohden ja kierrätä se, jos olet epävarma.
2. Mikä erottaa Experiment- ja Scale-suunnitelmat toisistaan?
Vastaus: Kiintiöt ja hinnoittelu: Experiment tutustumiseen ja prototyyppaukseen, Scale tuotantoon – tarkista rajasi konsolista ennen mitoittamista.
3. Mikä on ensimmäisen Python-kutsun runko?
Vastaus: Asiakas alustetaan avaimella, chat-kutsu tehdään mallilla ja viestilistalla, vastauksen sisältö luetaan – ja suoratoisto otetaan käyttöön progressiivista näyttämistä varten.
4. Miten käsittelet monivaiheista keskustelua API:n kautta?
Vastaus: Ylläpitämällä historiaa itse: jokainen pyyntö lähettää koko viestilistan (käyttäjä ja avustaja) – API on tilaton.
5. Mitä sinun tulee tietää käyttöönotoista Azuren, Vertexin tai Bedrockin kautta?
Vastaus: Mistral-mallit ovat saatavilla siellä valitun pilven todennuksella ja laskutuksella – sama malliperhe, eri päätepiste, hyödyllinen infrastruktuurirajoitteissa.
Avain turvattu, historia hallinnassa, suunnitelma sovitettu: lopulliset parhaat käytännöt muuttavat tämän perustan tuotantopohjaksi.