Πρώτη κλήση και ροή δεδομένων σε TypeScript
Σε αυτήν τη σελίδα
Μάθημα ενημερώθηκε στις 3 Νοεμβρίου 2026 μετά τη μεταγλώττιση παραδειγμάτων σε αυστηρή λειτουργία (strict mode) με το SDK
@mistralai/mistralai3.5.0 και TypeScript 7.0.2. Το SDK ορίζει τον τύπο τουcontentωςstring | ContentChunk[]: οι συνομιλίες πολλαπλών γύρων και οι βρόχοι ροής δεδομένων απέτυχαν να μεταγλωττιστούν χωρίς έλεγχοtypeof content === 'string'. Το παράδειγμα διαμόρφωσης συνδύαζε προηγουμένως τις παραμέτρουςtemperatureκαιtopP, κάτι που η τεκμηρίωση του API συμβουλεύει να μην γίνεται ταυτόχρονα. Ο χειρισμός σφαλμάτων χρησιμοποιεί πλέον την κλάσηMistralErrorτου SDK, και η διαδρομή Express επικυρώνει την ερώτηση πριν καλέσει το API. Πηγές: Mistral TypeScript SDK (README) · παράμετροι ολοκλήρωσης συνομιλίας.
Αποστολή του πρώτου αιτήματός σας
Τώρα που το SDK είναι εγκατεστημένο, ας περάσουμε στην πράξη. Η μέθοδος chat.complete() του TypeScript SDK είναι ο ακριβής αντίστοιχος της μεθόδου του Python SDK: ίδιες παράμετροι, ίδια δομή απόκρισης, εκτός από τις συμβάσεις ονοματοδοσίας. Αν ακολουθήσατε τα μαθήματα Python, βρίσκεστε σε οικείο έδαφος· η μόνη καινοτομία είναι η ασύγχρονη σύνταξη της JavaScript.
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();
Τα ερωτηματικά στο response.choices[0]?.message?.content δεν υπάρχουν απλώς για επίδειξη: στους τύπους του SDK, τα message και content είναι προαιρετικά, και το choices[0] δεν υπάρχει αν η λίστα επιστραφεί κενή. Η ασφαλής πρόσβαση επιστρέφει undefined αντί να ρίξει εξαίρεση. Σημειώστε επίσης ότι το content δεν είναι πάντα συμβολοσειρά: το SDK το ορίζει ως string | ContentChunk[] επειδή μια απόκριση μπορεί να φτάσει ως λίστα θραυσμάτων (κείμενο, συλλογισμός thinking, αναφορές κ.λπ.).
Κατανόηση της απόκρισης
Η δομή της απόκρισης είναι ίδια με αυτή του Python SDK. Η ανάλυσή της σάς βοηθά να κατανοήσετε για τι πληρώνετε και γιατί σταμάτησε μια απόκριση. Το παρακάτω παράδειγμα εξάγει το κείμενο, τον λόγο διακοπής και τον αριθμό των tokens ένα προς ένα· πληκτρολογώντας το, ο επεξεργαστής σας θα προτείνει κάθε πεδίο, αποδεικνύοντας ότι η τυποποίηση κάνει τη δουλειά της.
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,
});
// Κείμενο απόκρισης
const texte = response.choices[0]?.message?.content;
// Λόγος διακοπής
const finRaison = response.choices[0]?.finishReason;
// Στατιστικά tokens
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}`);
}
Προσέξτε τη χρήση πεζών/κεφαλαίων: εκεί που η Python εκθέτει τα max_tokens, finish_reason και prompt_tokens, το TypeScript χρησιμοποιεί τα maxTokens, finishReason και promptTokens. Αυτό είναι το νούμερο ένα σφάλμα κατά τη χειροκίνητη μεταφορά ενός παραδείγματος Python—και ο μεταγλωττιστής θα το επισημάνει αμέσως.
Ροή δεδομένων (Streaming)
Η ροή δεδομένων είναι απαραίτητη για τις διεπαφές ιστού: χωρίς αυτήν, ο χρήστης κοιτάζει μια παγωμένη οθόνη για αρκετά δευτερόλεπτα· με αυτήν, το κείμενο εμφανίζεται λέξη προς λέξη και η αντιληπτή καθυστέρηση καταρρέει. Το TypeScript SDK εκθέτει τη ροή ως έναν ασύγχρονο γεννήτορα (async generator), τον οποίο επαναλαμβάνετε με for await...of:
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();
}
Δύο λεπτομέρειες αξίζουν την προσοχή σας. Το περιεχόμενο βρίσκεται στο chunk.data, όχι απευθείας στο chunk: αυτό είναι το περίβλημα συμβάντος του SDK από την έκδοση 1.0. Και ο έλεγχος typeof content === 'string' φιλτράρει τόσο τα θραύσματα χωρίς περιεχόμενο, που θα γέμιζαν την έξοδό σας με undefined, όσο και το περιεχόμενο που είναι λίστα θραυσμάτων, το οποίο το process.stdout.write δεν δέχεται: χωρίς αυτόν, η αυστηρή λειτουργία αρνείται τη μεταγλώττιση.
Έκθεση της ροής μέσω Express
Μια ροή που δεν βγαίνει ποτέ από το τερματικό δεν ωφελεί κανέναν. Ορίστε πώς να την αναμεταδώσετε σε ένα πρόγραμμα περιήγησης χρησιμοποιώντας Server-Sent Events από ένα API Express. Η ερώτηση επικυρώνεται πριν από οποιαδήποτε κλήση για να αποφευχθεί η αποστολή κενού αιτήματος στο API. Οι τρεις κεφαλίδες ανοίγουν στη συνέχεια το κανάλι, κάθε θραύσμα στέλνεται πίσω ως JSON σε ένα συμβάν data:, και ένας δείκτης [DONE] σηματοδοτεί τον πελάτη να κλείσει τη σύνδεση.
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'));
Συνομιλίες πολλαπλών γύρων
Η διαχείριση του ιστορικού ακολουθεί την ίδια αρχή με την Python: το μοντέλο δεν έχει μνήμη, οπότε εσείς διατηρείτε έναν πίνακα μηνυμάτων και επαναστέλνετε το σύνολο κάθε γύρο. Στο TypeScript, η δήλωση ενός ρητού τύπου Message αποτρέπει την εισαγωγή μη υπάρχοντος ρόλου ή κακοδιατυπωμένου αντικειμένου—ένα σφάλμα που διαφορετικά το API θα επέστρεφε ως 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();
Ο έλεγχος typeof contenu === 'string' δεν είναι πολυτέλεια: το πεδίο content της απόκρισης μπορεί να είναι μια λίστα θραυσμάτων, ενώ ο τύπος Message σας αναμένει μια συμβολοσειρά. Παρατηρήστε στη συνέχεια την τρίτη ερώτηση: «Πώς προσθέτω περιορισμούς;» έχει νόημα μόνο επειδή οι δύο προηγούμενες ανταλλαγές βρίσκονται ακόμα στον πίνακα. Δοκιμάστε αφαιρώντας τη γραμμή που προσθέτει την απάντηση του βοηθού στο ιστορικό, και θα δείτε το μοντέλο να χάνει τη ροή του από τον δεύτερο γύρο.
Ρύθμιση παραγωγής και χειρισμός σφαλμάτων
Οι προηγμένες παράμετροι είναι ίδιες με αυτές του Python SDK—μόνο η χρήση πεζών/κεφαλαίων αλλάζει. Μια χαμηλή temperature για ένα δομημένο παραδοτέο και ένα maxTokens βαθμονομημένο στο αναμενόμενο μήκος αποδίδουν πιο προβλέψιμες αποκρίσεις. Ορίστε temperature ή topP, όχι και τα δύο: αυτή είναι η σύσταση της τεκμηρίωσης του API, η οποία συμβουλεύει τιμή temperature μεταξύ 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,
});
Τέλος, οποιαδήποτε κλήση δικτύου μπορεί να αποτύχει: μη έγκυρο κλειδί, υπέρβαση ορίου, διακοπή λειτουργίας. Περικλείετε πάντα την κλήση σε ένα try/catch και ελέγχετε τον τύπο του σφάλματος πριν διαβάσετε τις ιδιότητές του, διαφορετικά το TypeScript θα αρνηθεί τη μεταγλώττιση. Όλα τα σφάλματα HTTP που επιστρέφονται από το API κληρονομούν από το MistralError, το οποίο εκθέτει τα statusCode και body· τα σφάλματα δικτύου (ConnectionError, RequestTimeoutError κ.λπ.) δεν κληρονομούν από αυτό, αλλά παραμένουν στιγμιότυπα Error.
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: 401 απόρριψη κλειδιού, 429 επίτευξη ορίου...
console.error(`Mistral API Error ${error.statusCode}: ${error.message}`);
} else if (error instanceof Error) {
// Χωρίς απόκριση API: δίκτυο εκτός λειτουργίας, υπέρβαση χρονικού ορίου...
console.error(`Error: ${error.message}`);
}
}
Βασικά σημεία
- Το
client.chat.complete()είναι ασύγχρονο—χρησιμοποιήστεawait - Η ροή δεδομένων χρησιμοποιεί
for await...ofστο αποτέλεσμα τουclient.chat.stream() - Η τυποποίηση του TypeScript εντοπίζει σφάλματα παραμέτρων κατά τη μεταγλώττιση
- Η ενσωμάτωση SSE με το Express είναι απλή για διεπαφές ιστού σε πραγματικό χρόνο
- Το ιστορικό συνομιλίας διαχειρίζεται με έναν τυποποιημένο πίνακα
Message[] - Το
contentείναι είτε συμβολοσειρά είτε λίστα θραυσμάτων: ελέγξτεtypeof content === 'string'πριν το χρησιμοποιήσετε ως κείμενο - Τα σφάλματα HTTP του SDK κληρονομούν από το
MistralError(statusCode,body)