Guadagni:
- Può descrivere la struttura di base di una richiesta API LLM (endpoint, modello, messaggi, max_tokens)
- Comprende la differenza tra i ruoli di sistema, utente e assistente e la cronologia delle conversazioni stateless
- Può leggere e interpretare i campi (blocchi di contenuto, stop_reason, utilizzo) della risposta restituita
Nei moduli precedenti abbiamo utilizzato l'intelligenza artificiale da una finestra di chat. Ma se vuoi incorporare l'intelligenza artificiale nel tuo prodotto, automazione o flusso di lavoro, un'interfaccia di chat non sarà sufficiente; È necessario connettersi al modello a livello di codice, ovvero con codice o uno strumento di automazione. Il nome di questo ponte è API (Application Programming Interface, il contratto che permette a due software di dialogare secondo determinate regole). Al termine di questa unità, saprai cosa costituisce una richiesta API LLM (Large Language Model), quali ruoli del messaggio svolgono e come leggere la risposta. Questa è la base su cui verrà costruito il resto del modulo.
Come funziona l'API?
Il flusso di base nell'API è questo: invii una richiesta in un determinato formato; Il server restituisce una risposta in un formato specifico. Negli LLM, si tratta solitamente di una chiamata HTTP (HTTP: protocollo standard per trasportare richieste-risposte sul web) a un singolo indirizzo (endpoint, l'indirizzo fisso sul server che gestisce la tua richiesta). Ad esempio, in un'API di messaggistica, tutte le richieste vanno a un singolo indirizzo e vengono trasportate nel corpo come JSON (JavaScript Object Notation, un formato di testo costituito da coppie chiave/valore che può essere letto sia dagli esseri umani che dalle macchine).
In una richiesta specifichi almeno queste tre cose:
- Modello: quale modello utilizzerai (ad esempio un modello veloce ed economico o un modello potente).
- max_tokens: Il numero massimo di token (l'unità più piccola in cui viene elaborato il testo, che verrà elaborato in dettaglio nell'unità successiva) che il modello può produrre; cioè limite di uscita.
- messaggi: elenco dei messaggi che compongono la conversazione.
Passo dopo passo: come impostare una richiesta
- Preparare l'endpoint e le credenziali. Aggiungi la tua chiave API (la stringa segreta che dimostra la tua identità) alla richiesta in un'intestazione. Non incorpori mai la chiave nel codice; Tratteremo lo stoccaggio sicuro nell'unità 9.
- Selezionare il modello e il limite di output. Modello leggero + piccoli max_tokens per un compito semplice; Modello potente + limite più ampio per un compito complesso.
- Configura l'elenco dei messaggi. List the system instruction, user message, and past rounds (if any).
- Invia la richiesta e analizza la risposta. Leggere il contenuto del testo, il motivo dell'interruzione e l'utilizzo del token dal JSON restituito.
Ruoli del messaggio: sistema, utente, assistente
Una conversazione è composta da messaggi disposti in sequenza e ciascun messaggio ha un ruolo. Il ruolo determina il modo in cui il modello tratta quel testo.
Ruolo
Chi scrive
Scopo
sistema
Sviluppatore/operatore
Istruzioni permanenti, personalità e regole che si applicano durante l'intera conversazione
utente
utente finale
La domanda o l'input corrente dell'utente
assistente
modello
Risposta prodotta dal modello (e risposte precedenti)
Il ruolo di sistema è disponibile come campo di sistema separato nel corpo della richiesta nella maggior parte dei fornitori; l'utente e l'assistente vengono elencati in sequenza nell'elenco dei messaggi. Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.
{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "Sei un assistente di supporto aziendale. Fornisci una risposta breve, formale e verificata. Non inventare informazioni di cui non sei sicuro.", "messages": [ { "role": "user", "content": "Come posso avviare la procedura di reso?" } ]}
La parola è apolide
Ecco l'idea sbagliata più comune: le chiamate API LLM sono senza stato: il server non conserva memoria tra due richieste. Il modello non ricorda la tua richiesta precedente. Se stai impostando una chat a più round, dovrai inviare nuovamente i round precedenti con ogni nuova richiesta. La "memoria" del modello è costituita da un elenco di messaggi che hai inviato.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "Ciao, mi chiamo Deniz." }, { "role": "assistant", "content": "Ciao Deniz, come posso aiutarti?" }, { "role": "user", "content": "Ho appena detto il mio nome, ti ricordi?" } ]}
La risposta corretta al terzo messaggio dipende dall'invio di entrambi i messaggi precedenti. Se non lo invii, la modella non riconoscerà "Mare" e risponderà in modo errato. Ciò influisce direttamente anche sul costo: più lunga è la conversazione, più grande è l'elenco e ogni richiesta consuma più token.
Suggerimento: nelle conversazioni lunghe, riepilogare e spostare i vecchi round (riepilogo + ultimi round) invece di inviare l'intera cronologia riduce i costi e preserva la finestra di contesto. Approfondiremo questo aspetto nelle unità 6 e 11.
Leggi la risposta
Quando il modello restituisce una risposta, ricevi un oggetto strutturato, non testo semplice. Aree tipiche:
{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "Per avviare un reso, vai alla pagina 'I miei ordini' nel tuo account..." } ], "stop_reason": "end_turn", "usage": { "input_tokens": 47, "output_tokens": 88 }}
- contenuto: la risposta stessa; È un elenco di blocchi di contenuto. Il campo di testo del blocco di testo è la risposta effettiva.
- stop_reason: perché il modello si è fermato. fine_turno = fine naturale; max_tokens = bloccato al limite di output (la risposta potrebbe essere incompleta); rifiuto = rifiutato per motivi di sicurezza. Il tuo codice dovrebbe sempre guardare prima stop_reason.
- utilizzo: numeri di token di input e output. È la base del monitoraggio dei costi e dei limiti.
Attenzione: se stop_reason è max_tokens, la risposta non è completata. Trattarla come una "risposta positiva" e mostrare metà testo all'utente è uno degli errori più comuni nella produzione. Aumenta max_tokens o utilizza lo streaming.
Prompt debole / Prompt forte
Stessa attività con due diversi prompt di sistema:
# DEBOLESei un assistente. Rispondere alle domande.
# FORTESei un assistente di supporto aziendale. Regole: - Fare affidamento esclusivamente sulle informazioni contenute nel documento politico fornito; Se non è nel documento, dì "Non ho queste informazioni, le sto indirizzando all'unità competente". - Le risposte non devono superare le 3 frasi, essere formali e chiare. - Non chiedere dati personali (numero ID TC, numero carta) e non ripetere. - Non indovinare quando non sei sicuro.
Versione potente; Definisce l’ambito, la forma, il margine di sicurezza e il comportamento nell’incertezza. La coerenza del risultato del modello deriva direttamente da questa chiarezza.
Tre mini custodie
Caso 1 – Bot di supporto (trappola dell’apolidia). Un team di e-commerce ha messo in funzione il bot; Quando l'utente ha detto "annulla l'ordine precedente", il bot "ha dimenticato" il numero dell'ordine. Motivo: stavano inviando ogni richiesta solo con l'ultimo messaggio. Soluzione: hanno aggiunto gli ultimi 6 round all'elenco dei messaggi. Risultato: contesto preservato, ma input per richiesta aumentato da 40 token a ~600 token: tratteremo la lezione sui costi nell'unità 2.
Caso 2 — Sintesi contrattuale incompleta. Un team legale stava delineando contratti di 10 pagine; max_tokens: 300 rimanevano bassi, i riassunti venivano tagliati a metà frase. stop_reason era max_tokens ogni volta ma nessuno guardava. aumentato max_tokens a 1500 e aggiunto il controllo stop_reason; Il tasso di sintesi troncato è sceso dal 18% allo 0%.
Caso 3 – Miscelazione dei ruoli. Un team di marketing stava scrivendo tutte le istruzioni nel messaggio dell'utente, lasciando il sistema vuoto. Quando l'input dell'utente si mescolava alle istruzioni, il modello a volte rispettava il comando dell'utente di "dimenticare le regole precedenti". Hanno spostato regole permanenti nel sistema; Separando l’input dell’utente dalle istruzioni, le violazioni delle regole sono diminuite in modo significativo.
Errori comuni
- Dimenticare di trasmettere il passato: si pensa che il modello “non ricordi”; mentre è apolide. Tu porti il contesto.
- Non guardare `stop_reason`: la risposta interrotta con max_tokens è considerata completa.
- Incorporamento dell'istruzione in "utente": regole persistenti nel sistema; l'input istantaneo va all'utente. La mescolanza crea vulnerabilità nella sicurezza.
- Confondere `content` con una semplice stringa: la risposta è un elenco di blocchi; leggere il campo di testo del primo blocco di testo, verificarne il tipo prima di ottenere content[0] con un indice cieco.
- Incorporamento della chiave nel codice: utilizzare una variabile d'ambiente (unità 9).
Approfondimento: blocchi di contenuto e risposte in più parti
Capire perché il campo del contenuto nella risposta è un elenco è fondamentale per le funzionalità avanzate che incontrerai in seguito. A volte il modello non restituisce un singolo blocco di testo, ma diversi blocchi: un blocco di pensiero, seguito da un blocco di testo; o un blocco di testo seguito da un blocco di utilizzo dello strumento. Ecco perché contare ciecamente il contenuto[0] come "risposta" è fragile. L'approccio corretto è scorrere l'elenco e ordinarlo per tipo: raccogli il contenuto testuale dei blocchi il cui campo di tipo è testo e tratti gli altri tipi (pensiero, strumento) separatamente.
Ciò che questa distinzione fa in pratica è che è possibile registrare il ragionamento del modello (se presente) senza rivelarlo all'utente, reindirizzare le chiamate dello strumento a una logica separata e stampare solo la risposta effettiva sullo schermo. Man mano che il modulo procede (specialmente nelle unità 4 e 11) vedrai quanto sia utile questa struttura a blocchi per convalidare e dirigere l'output.
Altro punto pratico: è possibile accedere allo stesso modello da piattaforme di provider diversi (API diretta, tramite provider cloud). Sebbene l’indirizzo dell’endpoint e il formato di autenticazione possano cambiare, i concetti di base come i ruoli dei messaggi, l’apolidia e la struttura della risposta rimangono gli stessi. Pertanto, le nozioni di base di questa unità si applicano indipendentemente dalla piattaforma utilizzata.
In sintesi
Una richiesta API LLM è costituita dal modello, dal limite di output e dall'elenco dei messaggi; i ruoli (sistema, utente, assistente) determinano il comportamento del modello. Le chiamate sono stateless: porti con te il contesto con ogni richiesta. La risposta è un oggetto strutturato; Leggere e interpretare i campi contenuto, stop_reason e utilizzo è la base della durabilità nella produzione.
Compito dell'applicazione
Scegli un compito della tua professione (ad esempio smistare la posta elettronica in arrivo, creare brevi riassunti). Su un pezzo di carta: (1) scrivi il prompt di sistema con 4-5 regole, (2) imposta un messaggio utente di esempio e una cronologia di 2 round, se presente, (3) determina un valore ragionevole per max_tokens e scrivi la giustificazione, (4) elenca quali valori stop_reason gestirai nella risposta restituita e come.
lista di controllo
- [] Posso contare le tre parti obbligatorie di una richiesta (modello, max_tokens, messaggi).
- [ ] Posso spiegare la differenza tra i ruoli di sistema, utente e assistente.
- [ ] So che le chiamate sono apolidi e che ho bisogno di portarmi dietro il passato.
- Posso leggere e commentare [] contenuto, stop_reason e campi di utilizzo.
- [] Con max_tokens posso notare e gestire la risposta troncata.