Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Parhaat käytännöt ja seuraavat askeleet

Oppitunti 14 / 14 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Kurssin kertaus
  2. API-avainten suojaaminen
  3. Virheiden käsittely
  4. Nopeusrajoitusten kanssa eläminen
  5. Kustannusten hallinta
  6. Tapahtumien havainnointi
  7. Mitä seuraavaksi
  8. Keskeiset asiat
  9. Testaa tietämyksesi

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:

KoodiMerkitysToimenpide
401 UnauthorizedVirheellinen tai vanhentunut API-avainTarkista ympäristömuuttujasi
429 Too Many RequestsNopeusrajoitus saavutettuYritä uudelleen eksponentiaalisella viiveellä
500 Internal Server ErrorOngelma Mistralin puolellaAutomaattinen uudelleenyritys muutaman sekunnin kuluttua
503 Service UnavailableVäliaikainen ylikuormitusYritä 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.