Claude in Microsoft Foundry

Questa guida ti guida attraverso il processo di configurazione e di effettuazione di chiamate API a Claude in Foundry in Python, TypeScript o utilizzando richieste HTTP dirette. Quando puoi accedere a Claude in Foundry, ti viene addebitato l'utilizzo di Claude nel Microsoft Marketplace con la tua sottoscrizione Azure, permettendoti di accedere alle ultime funzionalità di Claude mentre gestisci i costi attraverso la tua sottoscrizione Azure.

Disponibilità regionale: Al lancio, Claude è disponibile come tipo di distribuzione Global Standard nelle risorse Foundry (US DataZone disponibile a breve). I prezzi per Claude nel Microsoft Marketplace utilizzano i prezzi API standard di Anthropic. Visita la pagina dei prezzi per i dettagli.

Anteprima

In questa integrazione della piattaforma di anteprima, i modelli Claude vengono eseguiti sull'infrastruttura di Anthropic. Questa è un'integrazione commerciale per la fatturazione e l'accesso tramite Azure. Come processore indipendente per Microsoft, i clienti che utilizzano Claude tramite Microsoft Foundry sono soggetti ai termini di utilizzo dei dati di Anthropic. Anthropic continua a fornire i suoi impegni di sicurezza e dati leader del settore, inclusa la disponibilità di zero data retention.

Prerequisiti

Prima di iniziare, assicurati di avere:

• Una sottoscrizione Azure attiva
• Accesso a Foundry
• Azure CLI installato (facoltativo, per la gestione delle risorse)

Installa un SDK

Gli SDK client di Anthropic supportano Foundry tramite pacchetti specifici della piattaforma.

Provisioning

Foundry utilizza una gerarchia a due livelli: le risorse contengono la tua configurazione di sicurezza e fatturazione, mentre le distribuzioni sono le istanze del modello che chiami tramite API. Innanzitutto creerai una risorsa Foundry, quindi creerai una o più distribuzioni Claude al suo interno.

Provisioning delle risorse Foundry

Crea una risorsa Foundry, che è necessaria per utilizzare e gestire i servizi in Azure. Puoi seguire queste istruzioni per creare una risorsa Foundry. In alternativa, puoi iniziare creando un progetto Foundry, che comporta la creazione di una risorsa Foundry.

Per eseguire il provisioning della tua risorsa:

1. Accedi al portale Foundry
2. Crea una nuova risorsa Foundry o selezionane una esistente
3. Configura la gestione dell'accesso utilizzando chiavi API emesse da Azure o Entra ID per il controllo dell'accesso basato su ruoli
4. Facoltativamente, configura la risorsa per far parte di una rete privata (Azure Virtual Network) per una sicurezza migliorata
5. Annota il nome della tua risorsa. Lo utilizzerai come {resource} negli endpoint API (ad esempio, https://{resource}.services.ai.azure.com/anthropic/v1/*)

Creazione di distribuzioni Foundry

Dopo aver creato la tua risorsa, distribuisci un modello Claude per renderlo disponibile per le chiamate API:

1. Nel portale Foundry, accedi alla tua risorsa
2. Vai a Models + endpoints e seleziona + Deploy model > Deploy base model
3. Cerca e seleziona un modello Claude (ad esempio, claude-sonnet-4-6)
4. Configura le impostazioni di distribuzione:
   • Deployment name: Predefinito all'ID del modello, ma puoi personalizzarlo (ad esempio, my-claude-deployment). Il nome della distribuzione non può essere modificato dopo la creazione.
   • Deployment type: Seleziona Global Standard (consigliato per Claude)
5. Seleziona Deploy e attendi il completamento del provisioning
6. Una volta distribuito, puoi trovare l'URL dell'endpoint e le chiavi in Keys and Endpoint

Autenticazione

Claude su Foundry supporta due metodi di autenticazione: chiavi API e token Entra ID. Entrambi i metodi utilizzano endpoint ospitati su Azure nel formato https://{resource}.services.ai.azure.com/anthropic/v1/*.

Autenticazione con chiave API

Dopo aver eseguito il provisioning della tua risorsa Claude Foundry, puoi ottenere una chiave API dal portale Foundry:

1. Accedi alla tua risorsa nel portale Foundry
2. Vai alla sezione Keys and Endpoint
3. Copia una delle chiavi API fornite
4. Utilizza l'intestazione api-key o x-api-key nelle tue richieste, oppure forniscila all'SDK

Gli SDK Python e TypeScript richiedono una chiave API e un nome di risorsa o un URL di base. Gli SDK leggeranno automaticamente questi dalle seguenti variabili di ambiente se definite:

• ANTHROPIC_FOUNDRY_API_KEY - La tua chiave API
• ANTHROPIC_FOUNDRY_RESOURCE - Il nome della tua risorsa (ad esempio, example-resource)
• ANTHROPIC_FOUNDRY_BASE_URL - Alternativa al nome della risorsa; l'URL di base completo (ad esempio, https://example-resource.services.ai.azure.com/anthropic/)

Esempio utilizzando la chiave API:

Autenticazione Microsoft Entra

Per una sicurezza migliorata e una gestione centralizzata dell'accesso, puoi utilizzare token Entra ID (precedentemente Azure Active Directory):

1. Abilita l'autenticazione Entra per la tua risorsa Foundry
2. Ottieni un token di accesso da Entra ID
3. Utilizza il token nell'intestazione Authorization: Bearer {TOKEN}

Esempio utilizzando Entra ID:

ID di richiesta di correlazione

Foundry include identificatori di richiesta negli header di risposta HTTP per il debug e la tracciamento. Quando contatti il supporto, fornisci sia i valori request-id che apim-request-id per aiutare i team a individuare e investigare rapidamente la tua richiesta su entrambi i sistemi Anthropic e Azure.

Funzionalità supportate

Claude su Foundry supporta la maggior parte delle potenti funzionalità di Claude. Puoi trovare tutte le funzionalità attualmente supportate nella documentazione di panoramica.

Finestra di contesto

Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 4.6 hanno una finestra di contesto di 1M token su Microsoft Foundry. Gli altri modelli Claude, incluso Sonnet 4.5, hanno una finestra di contesto di 200k token.

Funzionalità non supportate

• Admin API (endpoint /v1/organizations/*)
• Models API (/v1/models)
• Message Batch API (/v1/messages/batches)

Risposte API

Le risposte API da Claude su Foundry seguono il formato di risposta API Claude standard. Questo include l'oggetto usage nei corpi delle risposte, che fornisce informazioni dettagliate sul consumo di token per le tue richieste. L'oggetto usage è coerente su tutte le piattaforme (API di prima parte, Foundry, Amazon Bedrock e Google Vertex AI).

Per i dettagli sugli header di risposta specifici di Foundry, vedi la sezione ID di richiesta di correlazione.

ID modello API e distribuzioni

I seguenti modelli Claude sono disponibili tramite Foundry. I modelli di ultima generazione (Opus 4.7, Opus 4.6, Sonnet 4.6 e Haiku 4.5) offrono le capacità più avanzate:

Per impostazione predefinita, i nomi delle distribuzioni corrispondono agli ID dei modelli mostrati sopra. Tuttavia, puoi creare distribuzioni personalizzate con nomi diversi nel portale Foundry per gestire configurazioni, versioni o limiti di velocità diversi. Utilizza il nome della distribuzione (non necessariamente l'ID del modello) nelle tue richieste API.

Monitoraggio e registrazione

Azure fornisce funzionalità complete di monitoraggio e registrazione per il tuo utilizzo di Claude attraverso modelli Azure standard:

• Azure Monitor: Traccia l'utilizzo dell'API, la latenza e i tassi di errore
• Azure Log Analytics: Esegui query e analizza i log di richiesta/risposta
• Cost Management: Monitora e prevedi i costi associati all'utilizzo di Claude

Anthropic consiglia di registrare la tua attività su almeno una base mobile di 30 giorni per comprendere i modelli di utilizzo e investigare eventuali problemi potenziali.

Risoluzione dei problemi

Errori di autenticazione

Errore: 401 Unauthorized o Invalid API key

• Soluzione: Verifica che la tua chiave API sia corretta. Puoi ottenere una nuova chiave API dal portale Azure in Keys and Endpoint per la tua risorsa Claude.
• Soluzione: Se utilizzi Azure Entra ID, assicurati che il tuo token di accesso sia valido e non sia scaduto. I token in genere scadono dopo 1 ora.

Errore: 403 Forbidden

• Soluzione: Il tuo account Azure potrebbe non avere i permessi necessari. Assicurati di avere il ruolo Azure RBAC appropriato assegnato (ad esempio, "Cognitive Services OpenAI User").

Limitazione della velocità

Errore: 429 Too Many Requests

• Soluzione: Hai superato il tuo limite di velocità. Implementa la logica di backoff esponenziale e retry nella tua applicazione.
• Soluzione: Considera di richiedere aumenti del limite di velocità tramite il portale Azure o il supporto Azure.

Header di limite di velocità

Foundry non include gli header di limite di velocità standard di Anthropic (anthropic-ratelimit-tokens-limit, anthropic-ratelimit-tokens-remaining, anthropic-ratelimit-tokens-reset, anthropic-ratelimit-input-tokens-limit, anthropic-ratelimit-input-tokens-remaining, anthropic-ratelimit-input-tokens-reset, anthropic-ratelimit-output-tokens-limit, anthropic-ratelimit-output-tokens-remaining e anthropic-ratelimit-output-tokens-reset) nelle risposte. Gestisci la limitazione della velocità tramite gli strumenti di monitoraggio di Azure.

Errori di modello e distribuzione

Errore: Model not found o Deployment not found

• Soluzione: Verifica di utilizzare il nome di distribuzione corretto. Se non hai creato una distribuzione personalizzata, utilizza l'ID del modello predefinito (ad esempio, claude-sonnet-4-6).
• Soluzione: Assicurati che il modello/distribuzione sia disponibile nella tua regione Azure.

Errore: Invalid model parameter

• Soluzione: Il parametro del modello deve contenere il nome della tua distribuzione, che può essere personalizzato nel portale Foundry. Verifica che la distribuzione esista e sia configurata correttamente.

Risorse aggiuntive

• Documentazione Foundry: ai.azure.com/catalog
• Prezzi Azure: azure.microsoft.com/en-us/pricing
• Dettagli sui prezzi di Anthropic: Documentazione sui prezzi
• Guida all'autenticazione: Vedi la sezione autenticazione sopra
• Portale Azure: portal.azure.com