Claude in Microsoft Foundry

Questa guida ti accompagna attraverso il processo di configurazione ed esecuzione di chiamate API a Claude in Microsoft Foundry utilizzando uno degli SDK client di Anthropic o richieste HTTP dirette. Quando accedi a Claude in Microsoft Foundry, l'utilizzo di Claude viene fatturato nell'Azure Marketplace, consentendoti di accedere alle funzionalità più recenti di Claude gestendo al contempo i costi tramite la tua sottoscrizione Azure.

Claude è disponibile nei tipi di distribuzione Global Standard e US Data Zone Standard nelle risorse Foundry, fatturato in Claude Consumption Units tramite l'Azure Marketplace. Visita Prezzi per i dettagli.



Opzioni di hosting

I modelli Claude in Microsoft Foundry sono disponibili in due opzioni di hosting. Scegli l'opzione di hosting quando configuri la distribuzione.



Prerequisiti

Prima di iniziare, assicurati di avere:

• Una sottoscrizione Azure attiva
• Accesso a Foundry
• L'Azure CLI installata (opzionale, per la gestione delle risorse)



Installa un SDK

Gli SDK client di Anthropic supportano Foundry tramite un pacchetto o una classe client specifici per la piattaforma.



Provisioning

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



Provisioning delle risorse Foundry

Crea una risorsa Foundry, 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. Vai al portale Foundry
2. Crea una nuova risorsa Foundry o selezionane una esistente
3. Configura la gestione degli accessi utilizzando chiavi API emesse da Azure o Entra ID (precedentemente Azure Active Directory) per il controllo degli accessi basato sui ruoli
4. Facoltativamente, configura la risorsa affinché faccia parte di una rete privata (Azure Virtual Network) per una maggiore sicurezza
5. Prendi nota del 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. Questi passaggi descrivono il nuovo portale Foundry (l'interruttore New Foundry è attivo):

1. Accedi al portale Foundry. Dalla homepage del portale, seleziona Discover nella navigazione in alto a destra, quindi Models nel riquadro sinistro per aprire il catalogo dei modelli.
2. Cerca e seleziona un modello Claude (ad esempio, claude-opus-4-8). Ogni modello appare una sola volta nel catalogo indipendentemente dal numero di opzioni di hosting che supporta.
3. Nella scheda del modello, seleziona Deploy, quindi Custom settings per aprire il riquadro delle impostazioni di distribuzione. Se scegli invece Default settings, la distribuzione viene configurata automaticamente come Hosted on Azure per i modelli disponibili in entrambe le opzioni di hosting.
4. Alla tua prima distribuzione di Claude, esamina i termini dell'Azure Marketplace, seleziona un settore e seleziona Agree and Proceed per accettare i termini e sottoscrivere l'offerta dell'Azure Marketplace.
5. Configura la distribuzione:
   • Deployment name: Per impostazione predefinita corrisponde all'ID del modello, ma puoi personalizzarlo (ad esempio, my-claude-deployment). Il nome della distribuzione non può essere modificato dopo la creazione.
   • Region scope: Seleziona Global oppure, per i modelli ospitati su Azure, Data Zone. Selezionando Data Zone viene creata una distribuzione US Data Zone Standard, che mantiene l'inferenza all'interno degli Stati Uniti ed è equivalente a impostare inference_geo: "us" sull'API di Claude.
   • Model version: Espandi Model version settings e seleziona una versione dal menu a discesa Model version. Ogni opzione di hosting è elencata come versione del modello separata, etichettata con la relativa opzione di hosting (ad esempio, versione 1 per Hosted on Anthropic, versione 2 per Hosted on Azure).
6. Seleziona Deploy e attendi il completamento del provisioning.
7. Una volta completata la distribuzione, seleziona Build nella navigazione in alto a destra, quindi Models nel riquadro sinistro e apri la tua distribuzione. La scheda Details mostra il Target URI (l'URL del tuo endpoint) e la Key (la tua chiave API).



Autenticazione

Claude in Microsoft 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 in Foundry, puoi ottenere una chiave API dal portale Foundry:

1. Nel portale Foundry, seleziona Build nella navigazione in alto a destra, quindi Models nel riquadro sinistro.
2. Apri la tua distribuzione Claude e seleziona la scheda Details.
3. Copia il valore Key (e prendi nota del Target URI per il tuo endpoint).
4. Usa l'header api-key o x-api-key nelle tue richieste, oppure forniscilo all'SDK.

Gli SDK Foundry richiedono una chiave API e un nome di risorsa o un URL di base. Gli SDK C#, Java, PHP, Python e TypeScript leggono automaticamente questi valori dalle seguenti variabili d'ambiente se sono 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 con chiave API:



Autenticazione Microsoft Entra

Per una maggiore sicurezza e una gestione centralizzata degli accessi, puoi utilizzare i token Entra ID:

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

Esempio con Entra ID:



ID di correlazione delle richieste

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



Supporto delle funzionalità

Claude in Microsoft Foundry supporta la maggior parte delle potenti funzionalità di Claude. Puoi trovare tutte le funzionalità attualmente supportate in Panoramica delle funzionalità.



Finestra di contesto

Claude Fable 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 e Claude Sonnet 4.6 hanno una finestra di contesto da 1M di token su Microsoft Foundry. Altri modelli Claude, incluso Claude Sonnet 4.5, hanno una finestra di contesto da 200k token.



Funzionalità di Claude non supportate per Claude in Microsoft Foundry

• Admin API
• Strumento Advisor
• Claude Managed Agents
• Compliance API
• Models API
• Message Batches API
• Fallback lato server (il parametro fallbacks; usa invece il pattern di fallback lato client)



Funzionalità aggiuntive non supportate quando ospitato su Azure

Le seguenti funzionalità sono disponibili per le distribuzioni ospitate su Anthropic ma non sono supportate per le distribuzioni ospitate su Azure:

• Output strutturati
• Strumenti lato server (ricerca web, recupero web, esecuzione di codice e ricerca di strumenti)
• Connettore MCP
• Agent Skills
• Chiamata programmatica degli strumenti
• Files API

Le richieste che utilizzano queste funzionalità su una distribuzione ospitata su Azure restituiscono un errore 400 Bad Request per progettazione. Claude Code rileva le distribuzioni ospitate su Azure e adatta automaticamente il proprio set di funzionalità.



Risposte API

Le risposte API di Claude in Microsoft Foundry seguono il formato di risposta standard dell'API di Claude. 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 Claude, Foundry, Claude Platform su AWS, Amazon Bedrock e Google Cloud).

Per i dettagli sugli header di risposta specifici di Foundry, consulta ID di correlazione delle richieste.



ID modello API e distribuzioni

I termini del ciclo di vita (Deprecated, Retired) sono definiti in Deprecazioni dei modelli. Microsoft Foundry segue il calendario del ciclo di vita dell'API di Claude.

I seguenti modelli Claude sono disponibili tramite Foundry:

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



Fatturazione

Claude in Microsoft Foundry viene fatturato tramite l'Azure Marketplace. L'utilizzo è denominato in Claude Consumption Units (CCU), misurato su base oraria e fatturato mensilmente in via posticipata sulla tua fattura Azure. Le CCU non sono crediti prepagati; non esiste un saldo o un impegno in CCU.

Per il prezzo delle CCU, i meccanismi di conversione e le tariffe per token per modello, consulta Prezzi di Claude in Microsoft Foundry.



Migrazione tra opzioni di hosting

Per spostare una distribuzione esistente da un'opzione di hosting all'altra:

1. Crea una nuova distribuzione dell'altra versione di hosting del modello (Hosted on Azure o Hosted on Anthropic). Può trovarsi nella stessa risorsa Foundry o in una nuova.
2. Aggiorna la tua applicazione per passare il nuovo nome di distribuzione nel parametro model.
3. Elimina la vecchia distribuzione una volta che il traffico è stato spostato.

Se la nuova distribuzione si trova nella stessa risorsa Foundry, l'URL dell'endpoint e l'autenticazione rimangono invariati. Se hai creato una nuova risorsa, aggiorna l'endpoint e le credenziali della tua applicazione per puntare ad essa.



Monitoraggio e logging

Azure fornisce funzionalità complete di monitoraggio e logging per il tuo utilizzo di Claude tramite i pattern standard di Azure:

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

Anthropic consiglia di registrare la tua attività su base continuativa di almeno 30 giorni per comprendere i pattern di utilizzo e indagare su eventuali problemi.



Risoluzione dei problemi



Errori di autenticazione

Errore: 401 Unauthorized o Invalid API key

• Soluzione: Verifica che la tua chiave API sia corretta. Puoi trovarla nel portale Foundry nella scheda Details della tua distribuzione (sotto Build > Models).
• Soluzione: Se utilizzi Microsoft Entra ID, assicurati che il tuo token di accesso sia valido e non sia scaduto. I token scadono generalmente dopo 1 ora.

Errore: 403 Forbidden

• Soluzione: Il tuo account Azure potrebbe non disporre delle autorizzazioni necessarie. Assicurati di avere assegnato il ruolo Azure RBAC appropriato (ad esempio, Foundry User (precedentemente Azure AI User) o Cognitive Services User).



Limitazione della velocità

Errore: 429 Too Many Requests

• Soluzione: Hai superato il tuo limite di velocità. Implementa una 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 del limite di velocità

Foundry non include gli header standard del limite di velocità 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 invece 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, usa l'ID del modello predefinito (ad esempio, claude-sonnet-4-6).
• Soluzione: Assicurati che il modello/la distribuzione sia disponibile nella tua regione Azure.

Errore: Invalid model parameter

• Soluzione: Il parametro model 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/details/ai-foundry
• Dettagli sui prezzi Anthropic: Prezzi dei modelli
• Guida all'autenticazione: Consulta Autenticazione
• Portale Azure: portal.azure.com