API LLM per Sviluppatori: Guida Completa all'Integrazione

Questa guida copre tutto ciò che uno sviluppatore deve sapere per integrare le API LLM in applicazioni di produzione: autenticazione, streaming, uso di strumenti, embedding, pattern RAG e gestione dei costi. Tutti gli esempi utilizzano il formato compatibile con OpenAI e funzionano con APIMaster.ai.

Configurazione

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_APIMASTER_KEY",
    base_url="https://apimaster.ai/v1",
)

Pattern Principali

1. Completamento Chat di Base

def ask(prompt: str, model: str = "claude-sonnet-4-6") -> str:
    response = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content

2. Prompt di Sistema + Conversazione

class Conversation:
    def __init__(self, system: str, model: str = "claude-sonnet-4-6"):
        self.model = model
        self.messages = [{"role": "system", "content": system}]
    
    def send(self, user_msg: str) -> str:
        self.messages.append({"role": "user", "content": user_msg})
        resp = client.chat.completions.create(
            model=self.model,
            messages=self.messages,
        )
        reply = resp.choices[0].message.content
        self.messages.append({"role": "assistant", "content": reply})
        return reply

bot = Conversation("Sei uno sviluppatore Python esperto.")
print(bot.send("Cos'è il GIL?"))
print(bot.send("Come posso aggirarlo?"))

3. Streaming

def stream(prompt: str, model: str = "gpt-5.4"):
    with client.chat.completions.stream(
        model=model,
        messages=[{"role": "user", "content": prompt}],
    ) as s:
        for text in s.text_stream:
            yield text

for chunk in stream("Spiega async/await in Python"):
    print(chunk, end="", flush=True)

4. Output Strutturato

from pydantic import BaseModel
from typing import List

class ExtractedData(BaseModel):
    entities: List[str]
    sentiment: str
    summary: str

import json

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[
        {"role": "system", "content": f"Estrai i dati e restituisci JSON corrispondente a questo schema: {ExtractedData.schema()}"},
        {"role": "user", "content": "Apple ha riportato ricavi record. L'AD Tim Cook l'ha definito eccezionale."},
    ],
    response_format={"type": "json_object"},
)

data = ExtractedData(**json.loads(response.choices[0].message.content))
print(data.entities)    # ["Apple", "Tim Cook"]
print(data.sentiment)   # "positive"

5. Uso di Strumenti / Chiamata a Funzioni

import json

tools = [
    {
        "type": "function",
        "function": {
            "name": "execute_sql",
            "description": "Esegui una query SQL di sola lettura",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "database": {"type": "string", "enum": ["users", "orders", "products"]},
                },
                "required": ["query", "database"],
            },
        },
    }
]

def handle_tool_call(tool_name: str, args: dict) -> str:
    # La tua implementazione
    return json.dumps({"result": "dati fittizi"})

def agent_loop(user_msg: str):
    messages = [{"role": "user", "content": user_msg}]
    
    while True:
        resp = client.chat.completions.create(
            model="gpt-5.4",
            messages=messages,
            tools=tools,
        )
        
        if resp.choices[0].finish_reason != "tool_calls":
            return resp.choices[0].message.content
        
        # Elabora le chiamate agli strumenti
        messages.append(resp.choices[0].message)
        for tc in resp.choices[0].message.tool_calls:
            result = handle_tool_call(tc.function.name, json.loads(tc.function.arguments))
            messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})

6. Embedding

def embed(texts: list[str]) -> list[list[float]]:
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=texts,
    )
    return [item.embedding for item in response.data]

# Similarità semantica
import numpy as np

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

vecs = embed(["Python è fantastico", "Adoro Python", "Java è verboso"])
print(cosine_similarity(vecs[0], vecs[1]))  # Alto: ~0.95
print(cosine_similarity(vecs[0], vecs[2]))  # Più basso: ~0.70

7. RAG (Generazione Aumentata da Recupero)

from typing import List

def rag_query(user_question: str, knowledge_base: List[str]) -> str:
    # Passo 1: Crea l'embedding della domanda
    q_embedding = embed([user_question])[0]
    doc_embeddings = embed(knowledge_base)
    
    # Passo 2: Trova i documenti più rilevanti
    similarities = [cosine_similarity(q_embedding, d) for d in doc_embeddings]
    top_indices = sorted(range(len(similarities)), key=lambda i: similarities[i], reverse=True)[:3]
    context = "\n\n".join(knowledge_base[i] for i in top_indices)
    
    # Passo 3: Genera la risposta con il contesto
    response = client.chat.completions.create(
        model="claude-sonnet-4-6",
        messages=[
            {"role": "system", "content": f"Rispondi usando solo questo contesto:\n\n{context}"},
            {"role": "user", "content": user_question},
        ],
    )
    return response.choices[0].message.content

8. Async per Alto Throughput

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI(
    api_key="YOUR_APIMASTER_KEY",
    base_url="https://apimaster.ai/v1",
)

async def process_batch(prompts: list[str]) -> list[str]:
    tasks = [
        async_client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": p}],
            max_tokens=100,
        )
        for p in prompts
    ]
    responses = await asyncio.gather(*tasks)
    return [r.choices[0].message.content for r in responses]

# Elabora 50 prompt contemporaneamente
results = asyncio.run(process_batch(my_prompts))

Checklist per la Produzione

• Chiavi API in variabili d'ambiente, non nel codice sorgente
• Logica di retry con backoff esponenziale per errori 429/500
• max_tokens impostato per prevenire costi fuori controllo
• Streaming per risposte rivolte all'utente >2 secondi
• Log delle richieste con conteggio token per il monitoraggio dei costi
• Limitatore di velocità per rimanere entro i limiti del provider

Scegli il Modello Giusto

Caso d'Uso	Modello	Fascia di Costo
Prototipazione	deepseek-v4-flash o gpt-4o-mini	Molto basso
Chatbot di produzione	claude-haiku-4-5	Basso
Assistente di codice	deepseek-v4-flash o claude-sonnet-4-6	Basso–Medio
Analisi complessa	claude-sonnet-4-6	Medio
Ricerca/ragionamento	claude-opus-4-8 o o3	Alto

Domande Frequenti

Cos'è un'API LLM? Un'API LLM è un'interfaccia HTTP che permette al tuo codice di inviare prompt testuali e ricevere risposte generate dall'IA. Invii un array messages; l'API restituisce un completamento. La maggior parte utilizza il formato Chat Completions di OpenAI.

Come scelgo tra i provider di API LLM? Considera le capacità del modello (benchmark), il costo per token, la latenza e l'affidabilità. Per la maggior parte dei casi d'uso, DeepSeek V4 Flash (codifica a basso costo), Claude Sonnet (scrittura/analisi) o GPT-4o (multimodale) coprono i percorsi comuni. APIMaster ti permette di cambiare provider con una riga.

Cos'è un'API compatibile con OpenAI? Un endpoint che implementa lo stesso formato /v1/chat/completions di OpenAI, permettendoti di usare la libreria Python openai o qualsiasi strumento compatibile con OpenAI con modelli non OpenAI.

Come gestisco gli errori dell'API LLM in produzione? Gestisci RateLimitError (riprova con backoff), APIConnectionError (riprova) e InvalidRequestError (correggi il prompt). Usa timeout e circuit breaker per la resilienza in produzione.

Posso usare una sola chiave API per più provider LLM? Sì—APIMaster fornisce una singola chiave e un singolo endpoint per GPT, Claude, DeepSeek e Gemini. Cambia modello modificando il parametro model. Non sono necessarie chiavi o SDK specifici per provider.

Ottieni accesso all'API LLM → · Confronta modelli →