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

Ensimmäinen pyyntö ja suoratoisto TypeScriptillä

Oppitunti 9 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Lähetä ensimmäinen pyyntösi
  2. Suoratoisto (Streaming)
  3. Monivaiheiset keskustelut
  4. Generoinnin säätäminen ja virheenkäsittely
  5. Keskeiset asiat

Oppitunti päivitetty 3. marraskuuta 2026 sen jälkeen, kun esimerkit käännettiin tiukassa tilassa käyttäen SDK:ta @mistralai/mistralai 3.5.0 ja TypeScriptiä 7.0.2. SDK määrittää tyypin content muodossa string | ContentChunk[]: monivaiheiset keskustelut ja suoratoistosilmukat eivät kääntyneet ilman tarkistusta typeof content === 'string'. Aiempi konfiguraatioesimerkki yhdisti parametrit temperature ja topP, mitä API-dokumentaatio kehottaa välttämään samanaikaisesti. Virheenkäsittely käyttää nyt SDK:n MistralError-luokkaa, ja Express-reitti validoi kysymyksen ennen API-kutsua. Lähteet: Mistral TypeScript SDK (README) · chat completion parameters.

Lähetä ensimmäinen pyyntösi

Nyt kun SDK on asennettu, siirrytään käytäntöön. TypeScript-SDK:n metodi chat.complete() vastaa täysin Python-SDK:n metodia: samat parametrit, sama vastusrakenne, lukuun ottamatta nimentäkäytäntöjä. Jos olet seurannut Python-tunteja, olet tutulla maaperällä; uutena on vain JavaScriptin asynkroninen syntaksi.

import 'dotenv/config';
import { Mistral } from '@mistralai/mistralai';

const client = new Mistral({
  apiKey: process.env.MISTRAL_API_KEY,
});

async function main() {
  const response = await client.chat.complete({
    model: 'mistral-small-latest',
    messages: [
      {
        role: 'user',
        content: 'Explain the concept of a closure in JavaScript in three sentences.',
      },
    ],
  });

  console.log(response.choices[0]?.message?.content);
}

main();

Kysymysmerkit kohdassa response.choices[0]?.message?.content eivät ole vain koristeeksi: SDK-tyypeissä message ja content ovat valinnaisia, eikä choices[0] ole olemassa, jos lista palautuu tyhjänä. Turvallinen access palauttaa undefined sen sijaan, että heittäisi poikkeuksen. Huomaa myös, että content ei ole aina merkkijono: SDK määrittää sen tyypiksi string | ContentChunk[], koska vastaus voi saapua fragmenttien listana (teksti, thinking-päättely, viittaukset jne.).

Vastauksen ymmärtäminen

Vastusrakenne on identtinen Python-SDK:n kanssa. Sen jäsentäminen auttaa ymmärtämään, mistä maksat ja miksi vastaus pysähtyi. Seuraava esimerkki erittelee tekstin, pysäytyssyyn ja token-määrän yksi kerrallaan; koodaamalla tämän näet editorisi ehdottavan jokaista kenttää, mikä todistaa tyyppityksen toimivan.

async function analyserReponse() {
  const response = await client.chat.complete({
    model: 'mistral-small-latest',
    messages: [
      { role: 'user', content: 'What is the capital of France?' },
    ],
    maxTokens: 100,
  });

  // Vastausteksti
  const texte = response.choices[0]?.message?.content;

  // Pysäytyssyy
  const finRaison = response.choices[0]?.finishReason;

  // Token-tilastot
  const tokensEntree = response.usage?.promptTokens;
  const tokensSortie = response.usage?.completionTokens;

  console.log(`Response: ${texte}`);
  console.log(`Tokens: ${tokensEntree} input + ${tokensSortie} output`);
  console.log(`Stop: ${finRaison}`);
}

Huomaa kirjainkoko: missä Python tarjoaa max_tokens, finish_reason ja prompt_tokens, TypeScript käyttää muotoja maxTokens, finishReason ja promptTokens. Tämä on yleisin virhe siirrettäessä Python-esimerkkejä manuaalisesti – ja kääntäjä huomauttaa siitä välittömästi.

Suoratoisto (Streaming)

Suoratoisto on välttämätöntä verkkokäyttöliittymissä: ilman sitä käyttäjä tuijottaa jäätyneenä näyttöä useita sekunteja; sen kanssa teksti ilmestyy sana sanalta ja koettu viive romahtaa. TypeScript-SDK tarjoaa virran async-generaattorina, jota iteroidaan for await...of-rakenteella:

async function streamReponse() {
  const stream = await client.chat.stream({
    model: 'mistral-small-latest',
    messages: [
      {
        role: 'user',
        content: 'Describe the five main design patterns in JavaScript.',
      },
    ],
  });

  for await (const chunk of stream) {
    const content = chunk.data.choices[0]?.delta.content;
    if (typeof content === 'string') {
      process.stdout.write(content);
    }
  }
  console.log();
}

Kaksi yksityiskohtaa ansaitsevat huomiosi. Sisältö sijaitsee kohdassa chunk.data, ei suoraan chunk-objektissa: tämä on SDK:n tapahtumakääre versiosta 1.0 lähtien. Tarkistus typeof content === 'string' suodattaa pois sekä sisältöä vailla olevat fragmentit, jotka sotkisivat tulosteesi undefined-arvoilla, että fragmenttilistat, joita process.stdout.write ei hyväksy: ilman tätä tiukka tila kieltäytyy kääntämästä koodia.

Virran jakaminen Expressin kautta

Suoratoisto, joka ei koskaan poistu päätteestä, ei hyödytä ketään. Tässä näet, kuinka välität sen selaimelle käyttäen Server-Sent Events -tekniikkaa Express-API:ssa. Kysymys validoidaan ennen mitään kutsua, jotta vältetään tyhjän pyynnön lähettäminen API:lle. Kolme otsikkoa avaavat kanavan, jokainen fragmentti lähetetään takaisin JSON-muodossa data:-tapahtumana, ja [DONE]-merkki ilmoittaa asiakkaalle sulkevansa yhteyden.

import express from 'express';
import { Mistral } from '@mistralai/mistralai';

const app = express();
const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

app.get('/api/chat', async (req, res) => {
  const question = typeof req.query.q === 'string' ? req.query.q : '';
  if (!question) {
    res.status(400).json({ error: 'Missing q parameter' });
    return;
  }

  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  const stream = await client.chat.stream({
    model: 'mistral-small-latest',
    messages: [{ role: 'user', content: question }],
  });

  for await (const chunk of stream) {
    const content = chunk.data.choices[0]?.delta.content;
    if (typeof content === 'string' && content) {
      res.write(`data: ${JSON.stringify({ text: content })}\n\n`);
    }
  }

  res.write('data: [DONE]\n\n');
  res.end();
});

app.listen(3000, () => console.log('Server on port 3000'));

Monivaiheiset keskustelut

Historian hallinta noudattaa samaa periaatetta kuin Pythonissa: mallilla ei ole muistia, joten ylläpidät viestitaulukkoa ja lähetät koko sisällön uudelleen jokaisella vuorolla. TypeScriptissä eksplisiittisen Message-tyypin määrittäminen estää virheellisen roolin tai väärin muotoillun objektin syöttämisen – virheen, jonka API muuten palauttaisi koodilla 400.

import { Mistral } from '@mistralai/mistralai';

type Message = {
  role: 'system' | 'user' | 'assistant';
  content: string;
};

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const historique: Message[] = [
  {
    role: 'system',
    content: 'You are an expert TypeScript assistant. Respond in English.',
  },
];

async function poserQuestion(question: string): Promise<string> {
  historique.push({ role: 'user', content: question });

  const response = await client.chat.complete({
    model: 'mistral-small-latest',
    messages: historique,
  });

  const contenu = response.choices[0]?.message?.content;
  const reponse = typeof contenu === 'string' ? contenu : '';
  historique.push({ role: 'assistant', content: reponse });

  return reponse;
}

async function main() {
  console.log(await poserQuestion('What is a generic type?'));
  console.log(await poserQuestion('Show me a concrete example.'));
  console.log(await poserQuestion('How do I add constraints?'));
}

main();

Tarkistus typeof contenu === 'string' ei ole ylellisyyttä: vastauksen content-kenttä voi olla fragmenttilista, kun taas Message-tyyppisi odottaa merkkijonoa. Huomaa sitten kolmas kysymys: “How do I add constraints?” saa merkityksensä vain, koska kaksi edellistä vaihtoa ovat edelleen taulukossa. Haasta itsesi poistamalla rivi, joka lisää avustajan vastauksen historiaan, ja huomaat mallin menettävän langan toisella vuorolla.

Generoinnin säätäminen ja virheenkäsittely

Edistyneet parametrit ovat identtisiä Python-SDK:n kanssa – vain kirjainkoko muuttuu. Matala temperature strukturoituun tuotokseen ja odotettuun pituuteen mitoitettu maxTokens tuottavat ennustettavampia vastauksia. Aseta joko temperature tai topP, älä molempia: tämä on API-dokumentaation suositus, joka neuvoo käyttämään temperature-arvoa välillä 0–0,7.

const response = await client.chat.complete({
  model: 'mistral-large-latest',
  messages: [
    { role: 'user', content: 'Propose an architecture for a B2B SaaS.' },
  ],
  temperature: 0.5,
  maxTokens: 1000,
});

Lopuksi, mikä tahansa verkkokutsu voi epäonnistua: virheellinen avain, kiintiön ylitys tai katkos. Kääri kutsu aina try/catch-lohkoon ja tarkista virheen tyyppi ennen sen ominaisuuksien lukemista, muuten TypeScript kieltäytyy kääntämästä koodia. Kaikki API:n palauttamat HTTP-virheet periytyvät luokasta MistralError, joka tarjoaa ominaisuudet statusCode ja body; verkkovirheet (ConnectionError, RequestTimeoutError jne.) eivät periydy siitä, mutta ovat edelleen Error-instansseja.

import * as errors from '@mistralai/mistralai/models/errors';

try {
  const response = await client.chat.complete({
    model: 'mistral-small-latest',
    messages: [{ role: 'user', content: 'Hello!' }],
  });
  console.log(response.choices[0]?.message?.content);
} catch (error) {
  if (error instanceof errors.MistralError) {
    // API-virhevastaus: 401 avain hylätty, 429 raja saavutettu...
    console.error(`Mistral API Error ${error.statusCode}: ${error.message}`);
  } else if (error instanceof Error) {
    // Ei API-vastausta: verkko alhaalla, aikakatkaisu ylitetty...
    console.error(`Error: ${error.message}`);
  }
}

Keskeiset asiat

  • client.chat.complete() on asynkroninen – käytä await
  • Suoratoisto käyttää for await...of-rakennetta client.chat.stream()-tulokselle
  • TypeScript-tyypitys havaitsee parametrivirheet käännösvaiheessa
  • SSE-integraatio Expressin kanssa on suoraviivaista reaaliaikaisille verkkokäyttöliittymille
  • Keskusteluhistoriaa hallitaan tyypitetyllä Message[]-taulukolla
  • content on joko merkkijono tai fragmenttilista: testaa typeof content === 'string' ennen sen käyttöä tekstinä
  • SDK:n HTTP-virheet periytyvät luokasta MistralError (statusCode, body)