SDK Python di Anthropic: installazione, configurazione di base_url, streaming e gestione degli errori

La anthropic è il pacchetto client Python ufficiale di Anthropic per l'API di Claude. Gestisce autenticazione, tentativi successivi, streaming ed errori tipizzati e funziona senza modifiche con qualsiasi endpoint compatibile con Anthropic: imposta base_url (oppure ANTHROPIC_BASE_URL) e il resto del codice rimane invariato.

Installazione

pip install anthropic

Le versioni 1.x funzionano su httpx2 e richiedono Python 3.10 o successivo. Se passi un tuo client HTTP, usa DefaultHttpxClient dell'SDK per mantenere i timeout e i limiti di connessione predefiniti.

Creare un client

import anthropic

client = anthropic.Anthropic(
    api_key="your_key",   # default: ANTHROPIC_API_KEY
    base_url="https://aiprimetech.io",    # default: ANTHROPIC_BASE_URL, else https://api.anthropic.com
)

base_url è l'URL radice dell'host. L'SDK aggiunge /v1/messages automaticamente, quindi https://aiprimetech.io/v1 produrrebbe /v1/v1/messages e un 404 page not found. Con entrambe le variabili impostate nell'ambiente, anthropic.Anthropic() non richiede alcun argomento:

export ANTHROPIC_API_KEY=your_key
export ANTHROPIC_BASE_URL=https://aiprimetech.io

Inviare un messaggio

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Summarise TCP slow start in two sentences."}],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

print(message.usage.input_tokens, message.usage.output_tokens)
print(message._request_id)   # log this with any failure report

content è un elenco di blocchi (testo, ragionamento, uso di strumenti), quindi controlla block.type invece di leggere content[0].text alla cieca.

Ricevere risposte in streaming

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Write a short story about a lighthouse."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()

Usa lo streaming per qualsiasi richiesta con input lungo, output lungo o un valore elevato di max_tokens: una singola richiesta senza streaming deve terminare entro il timeout; una richiesta in streaming no. messages.create(..., stream=True) fornisce l'iteratore degli eventi grezzi se non hai bisogno della funzione di supporto.

Client asincrono

import asyncio, anthropic

client = anthropic.AsyncAnthropic(base_url="https://aiprimetech.io")
limit = asyncio.Semaphore(3)   # stay within your key's concurrency

async def ask(question: str) -> str:
    async with limit:
        msg = await client.messages.create(
            model="claude-haiku-4-5",
            max_tokens=512,
            messages=[{"role": "user", "content": question}],
        )
        return next(b.text for b in msg.content if b.type == "text")

async def main():
    answers = await asyncio.gather(*(ask(q) for q in ["What is DNS?", "What is BGP?"]))
    print(answers)

asyncio.run(main())

Il semaforo è importante. Inviare centinaia di richieste contemporaneamente con asyncio.gather è la causa più comune degli errori Concurrency limit exceeded che riscontriamo nei client Python.

Timeout e nuovi tentativi

Valori predefiniti: un timeout di 10 minuti per richiesta e 2 tentativi automatici con backoff esponenziale. L'SDK ritenta in caso di errori di connessione e risposte 408, 409, 429 e 5xx. Poiché ritenta anche in caso di timeout, il tempo totale nel caso peggiore è pari al timeout moltiplicato per il numero di tentativi.

client = anthropic.Anthropic(base_url="https://aiprimetech.io", timeout=60.0, max_retries=4)

# override for one call only
client.with_options(timeout=300.0).messages.create(
    model="claude-opus-5-5",
    max_tokens=4000,
    messages=[{"role": "user", "content": "Review this design doc..."}],
)

Gestione degli errori

try:
    message = client.messages.create(model="claude-sonnet-5", max_tokens=1024,
                                      messages=[{"role": "user", "content": "Hi"}])
except anthropic.NotFoundError as e:
    print("Bad model ID or URL:", e.message)
except anthropic.RateLimitError as e:
    print("Rate limited, retry after", e.response.headers.get("retry-after"))
except anthropic.APIStatusError as e:
    print(e.status_code, e.type, e.message)
except anthropic.APIConnectionError:
    print("Network problem")

Intercetta prima le classi specifiche e APIStatusError per ultima; una singola except generica nasconde la differenza tra gli errori per cui vale la pena ritentare e quelli che richiedono una modifica al codice. e.type fornisce la stringa del tipo di errore dell'API, ad esempio rate_limit_error o overloaded_error.

ID dei modelli

client.models.list() restituisce i modelli disponibili su un endpoint, così puoi verificare un ID prima di usarlo. Usa gli ID esattamente come sono scritti, senza suffissi di data.

Risoluzione dei problemi su un gateway

Per approfondire gli errori lato modello, consulta la guida agli errori dell'API di Claude.

Domande frequenti

AI Prime Tech è un gateway API indipendente. Non è affiliato ad Anthropic, non è approvato da Anthropic e non è un suo rivenditore. Claude e i nomi dei modelli correlati sono marchi dei rispettivi proprietari.