Πρώτη Ενσωμάτωση LLM API σε Production
Καλέστε LLM API από τον server με ασφαλές κλειδί, timeout και Zod validation.
Έλεγχος περιεχομένου: 2026-11-09
10 min ανάγνωση • RoboSchool Engineering
Η ενσωμάτωση Large Language Models (LLMs) όπως το Claude, το GPT-4o ή το Gemini σε παραγωγικές web εφαρμογές διαφέρει ριζικά από ένα απλό demo script. Στην παραγωγή απαιτείται απόλυτη προστασία API keys, διαχείριση timeouts, εγγύηση δομημένης εξόδου (Structured Outputs) και έλεγχος κόστους.
Προαπαιτούμενα
Self-hosted μοντέλα (βλ. Ollama & vLLM στο VPS).
1. Απαραβίαστη Ασφάλεια Κλειδιών με server-only
Το API Key ενός μοντέλου τεχνητής νοημοσύνης δεν πρέπει ΠΟΤΕ να εκτεθεί στον browser. Ένα εκτεθειμένο κλειδί μπορεί να εξαντλήσει το όριο χρέωσής σας σε λίγα λεπτά:
// lib/ai/client.ts
import 'server-only' // Εγγυάται compilation error εάν το αρχείο εισαχθεί σε Client Component!
// Ένα κλειδί ανά πάροχο: τα παραδείγματα αυτού του οδηγού καλούν το OpenAI API.
export const apiKey = process.env.OPENAI_API_KEY;
if (!apiKey) {
throw new Error('MISSING_AI_KEY: Παρακαλούμε ορίστε το OPENAI_API_KEY στο περιβάλλον.');
}2. Διαχείριση Timeouts με AbortController
Τα αιτήματα σε LLM APIs μπορεί να καθυστερήσουν σημαντικά. Χωρίς timeout, ο serverless worker σας θα παραμείνει δεσμευμένος μέχρι το hard execution limit, αυξάνοντας το κόστος υποδομής:
import { apiKey } from './client';
export async function callModelWithTimeout(prompt: string, timeoutMs = 15000) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const res = await fetch('https://api.openai.com/v1/chat/completions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${apiKey}`,
},
body: JSON.stringify({
model: 'gpt-4o-mini',
max_tokens: 2000,
// Η λέξη "json" μέσα στα messages είναι ΥΠΟΧΡΕΩΤΙΚΗ για το json_object — αλλιώς το API επιστρέφει 400.
messages: [{ role: 'user', content: prompt + '\nΑπάντησε αποκλειστικά σε JSON.' }],
response_format: { type: 'json_object' },
}),
signal: controller.signal,
});
if (res.status === 400) {
const detail = await res.text().catch(() => '');
throw new Error(`LLM API 400: λείπει η λέξη "json" από τα messages ή το prompt παραβιάζει το σχήμα. ${detail.slice(0, 200)}`);
}
if (!res.ok) {
throw new Error(`LLM API returned status ${res.status}`);
}
return await res.json();
} catch (err: unknown) {
if (err instanceof Error && err.name === 'AbortError') {
throw new Error(`Το αίτημα προς το AI μοντέλο έληξε λόγω χρονικού ορίου (${timeoutMs}ms).`);
}
throw err;
} finally {
clearTimeout(timer);
}
}3. Επικύρωση Δομημένης Εξόδου (Structured Outputs) με Zod
Τα LLMs είναι πιθανοτικά συστήματα (probabilistic) και ενδέχεται να επιστρέψουν μη έγκυρο JSON ή να παραλείψουν πεδία. Η επικύρωση με Zod είναι υποχρεωτική:
import { z } from 'zod'
// Καθορισμός του αναμενόμενου σχήματος απάντησης
const CodeReviewResponseSchema = z.object({
score: z.number().min(0).max(100),
summary: z.string().min(10),
criticalIssues: z.array(
z.object({
file: z.string(),
line: z.number().int().positive().optional(),
description: z.string(),
suggestion: z.string(),
})
),
});
export type CodeReviewResult = z.infer<typeof CodeReviewResponseSchema>;
export function parseAIReviewResponse(rawJson: unknown): CodeReviewResult {
const parsed = CodeReviewResponseSchema.safeParse(rawJson);
if (!parsed.success) {
console.error('[AI Schema Mismatch]', parsed.error.format());
throw new Error('Η απάντηση του AI μοντέλου δεν συμμορφώνεται με το αναμενόμενο σχήμα δεδομένων.');
}
return parsed.data;
}4. Production Checklist για Ενσωμάτωση LLM
| Έλεγχος | Κατάσταση | Σκοπός |
|---|---|---|
| Ασφάλεια Κλειδιού | server-only import | Μηδενική πιθανότητα διαρροής στο client bundle |
| Timeout Protection | AbortController (15s-30s) | Αποτροπή παγωμένων Serverless functions |
| Έλεγχος Κόστους | max_tokens + spend limits | Όριο tokens/€ ανά κλήση |
| Output Validation | Strict Zod Schema validation | Προστασία downstream UI από null pointer errors |
| Structured Outputs | response_format: { type: 'json_schema', json_schema: {...} } (προτείνεται) | Αυστηρό σχήμα αντί για ελεύθερο json_object όπου γίνεται |
| Fallback Μηχανισμός | Static graceful degradation | Εμφάνιση εναλλακτικής βοήθειας σε περίπτωση API outage |
response_format: { type: 'json_object' }Ποια λέξη πρέπει να περιέχουν τα messages για το json_object;
Ανακεφαλαίωση
server-onlyγια το API key — ποτέ στο client bundle.AbortControllertimeout 15-30s + ρητό 400 handling για τοjson_object.- Zod validation σε κάθε απάντηση· προτιμήστε Structured Outputs
json_schemaόπου γίνεται.