Usa modelli di ragionamento con Microsoft Foundry Models

I modelli di ragionamento usano calcoli aggiuntivi per risolvere problemi complessi prima di restituire una risposta. Questo articolo illustra come richiamare un modello di ragionamento non di OpenAI, DeepSeek-V4-Pro, usando l'API Chat Completions di OpenAI in un progetto Foundry.

Prerequisiti

Una sottoscrizione di Azure.
Un progetto di Foundry. Questo tipo di progetto viene gestito tramite una risorsa Foundry. Se non si ha un progetto Foundry, vedere Creare un progetto per Microsoft Foundry.
L'URL dell'endpoint del tuo progetto Foundry, che è del formato https://YOUR-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR_PROJECT_NAME.
Modello di ragionamento distribuito. Questo articolo usa DeepSeek-V4-Pro; sostituire il nome del modello con il nome della distribuzione quando necessario.
SDK o strumenti da riga di comando per il linguaggio selezionato. Per C#, usare .NET 10 SDK. Gli esempi C# vengono testati con i OpenAI pacchetti 2.13.0 e Azure.Identity 1.21.0.
Autorizzazione per accedere al progetto e alla distribuzione del modello. Per l'autenticazione senza chiave, accedere con un'identità che dispone dell'accesso richiesto al progetto Foundry.

Usare lo starter kit del modello di intelligenza artificiale

Gli esempi nello starter kit del modello di IA utilizzano i client OpenAI standard con un endpoint di progetto di Foundry e il percorso /openai/v1. Lo starter kit include un esempio completo per un modello di ragionamento DeepSeek. Gli esempi correnti usano l'API Risposte. Gli esempi in questo articolo utilizzano Chat Completions con distribuzioni che espongono tale API.

Configurare il client

Usare Microsoft Entra ID per autenticare il client OpenAI. L'ambito del token per l'endpoint del progetto Foundry è https://ai.azure.com/.default. L'endpoint deve essere l'endpoint del progetto, non l'endpoint della risorsa e l'URL di base del client deve aggiungere /openai/v1.

Installare openai e azure-identity librerie.

pip install --upgrade openai azure-identity

Usare il codice seguente per configurare l'oggetto client OpenAI nella route del progetto.

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import OpenAI

project_endpoint = "https://<resource>.services.ai.azure.com/api/projects/<project>"
token_provider = get_bearer_token_provider(
              DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
              base_url=project_endpoint.rstrip("/") + "/openai/v1",
              api_key=token_provider,
)

Installare openai e @azure/identity.
```
npm install openai @azure/identity
```

Usare il codice seguente per configurare l'oggetto client OpenAI nella route del progetto:

import OpenAI from "openai";
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";

const projectEndpoint = "https://<resource>.services.ai.azure.com/api/projects/<project>";
const tokenProvider = getBearerTokenProvider(
       new DefaultAzureCredential(), "https://ai.azure.com/.default"
);
const client = new OpenAI({
       baseURL: `${projectEndpoint.replace(/\/+$/, "")}/openai/v1`,
       apiKey: tokenProvider,
});

Aggiungere openai-java e azure-identity al progetto, quindi configurare l'oggetto client OpenAI nella route del progetto. Il modello client seguente usa OpenAI Java SDK e il provider di token Entra:

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import com.azure.identity.AuthenticationUtil;

String projectEndpoint = "https://<resource>.services.ai.azure.com/api/projects/<project>";
OpenAIClient client = OpenAIOkHttpClient.builder()
              .baseUrl(projectEndpoint.replaceAll("/+$", "") + "/openai/v1")
              .credential(BearerTokenCredential.create(AuthenticationUtil.getBearerTokenSupplier(
                            new DefaultAzureCredentialBuilder().build(), "https://ai.azure.com/.default")))
              .build();

Installare i pacchetti OpenAI e Azure.Identity

dotnet add package OpenAI --version 2.13.0
dotnet add package Azure.Identity --version 1.21.0

Usare il codice seguente per configurare l'oggetto client OpenAI nella route del progetto.

using Azure.Identity;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel.Primitives;

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
              new DefaultAzureCredential(), "https://ai.azure.com/.default");
ChatClient client = new(
              model: "DeepSeek-V4-Pro", // Replace with your deployment name, not the model ID 
              authenticationPolicy: tokenPolicy,
              options: new OpenAIClientOptions { Endpoint = new Uri(
                            "https://<resource>.services.ai.azure.com/api/projects/<project>/openai/v1") });

Ottenere un token Entra per l'ambito https://ai.azure.com/.default e inviarlo come token di connessione. Non è richiesto alcun parametro di query per /openai/v1.

export AZURE_AI_AUTH_TOKEN="<entra-token>"

Crea un completamento della chat di base

Inviare un messaggio utente al modello di ragionamento distribuito. La risposta contiene la risposta finale in message.content. A seconda del modello, la risposta può contenere anche contenuto di ragionamento in message.reasoning_content.

response = client.chat.completions.create(
              model="DeepSeek-V4-Pro", # Replace with your deployment name, not the model ID
              messages=[{"role": "user", "content": "How many languages are spoken worldwide?"}],
)
print(response.choices[0].message.content)
print(getattr(response.choices[0].message, "reasoning_content", None))

const response = await client.chat.completions.create({
       model: "DeepSeek-V4-Pro", // Replace with your deployment name, not the model ID
       messages: [{ role: "user", content: "How many languages are spoken worldwide?" }],
});
console.log(response.choices[0]?.message.content);
console.log(response.choices[0]?.message.reasoning_content);

import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
              .model("DeepSeek-V4-Pro") // Replace with your deployment name, not the model ID
              .addUserMessage("How many languages are spoken worldwide?")
              .build();
ChatCompletion response = client.chat().completions().create(params);
System.out.println(response.choices().get(0).message().content().orElse(""));

ChatCompletion response = await client.CompleteChatAsync([
              new UserChatMessage("How many languages are spoken worldwide?")
]);
Console.WriteLine(response.Content[0].Text);

curl -X POST "https://<resource>.services.ai.azure.com/api/projects/<project>/openai/v1/chat/completions" \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
       -d '{
              "model": "DeepSeek-V4-Pro",
              "messages": [{"role": "user", "content": "How many languages are spoken worldwide?"}]
       }'

Leggere il contenuto di ragionamento

Alcuni modelli di ragionamento non OpenAI restituiscono un campo reasoning_content insieme al content finale. Il contenuto di ragionamento può essere lungo e conta per l'utilizzo dei token. Non aggiungerlo alla cronologia dei messaggi per una conversazione a più turni, a meno che la documentazione del modello non lo richieda in modo specifico. Archiviarlo o visualizzarlo solo quando l'applicazione lo richiede e considerarlo come output del modello anziché una spiegazione verificata.

Per i modelli che non restituiscono reasoning_content, usare il valore finale content . Il campo è dipendente dal modello e non è disponibile per ogni modello di ragionamento.

Eseguire lo streaming di un completamento

Imposta stream su true per ricevere eventi inviati dal server mentre il modello genera l'output. I contenuti del ragionamento e della risposta finale possono arrivare in campi delta diversi. Gli esempi seguenti stampano il contenuto della risposta finale man mano che arriva.

stream = client.chat.completions.create(
              model="DeepSeek-V4-Pro",
              messages=[{"role": "user", "content": "Explain photosynthesis briefly."}],
              stream=True,
)
for event in stream:
              if event.choices:
                            content = event.choices[0].delta.content
                            if content:
                                          print(content, end="", flush=True)

const stream = await client.chat.completions.create({
       model: "DeepSeek-V4-Pro",
       messages: [{ role: "user", content: "Explain photosynthesis briefly." }],
       stream: true,
});
for await (const event of stream) {
       const content = event.choices[0]?.delta?.content;
       if (content) process.stdout.write(content);
}

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
              .model("DeepSeek-V4-Pro")
              .addUserMessage("Explain photosynthesis briefly.")
              .build();
client.chat().completions().createStreaming(params).stream()
              .flatMap(chunk -> chunk.choices().stream())
              .flatMap(choice -> choice.delta().content().stream())
              .forEach(System.out::print);

var stream = client.CompleteChatStreamingAsync([
              new UserChatMessage("Explain photosynthesis briefly.")
]);
await foreach (StreamingChatCompletionUpdate update in stream)
{
              foreach (ChatMessageContentPart part in update.ContentUpdate)
              {
                            Console.Write(part.Text);
              }
}

curl -N -X POST "https://<resource>.services.ai.azure.com/api/projects/<project>/openai/v1/chat/completions" \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
       -d '{"model":"DeepSeek-V4-Pro","messages":[{"role":"user","content":"Explain photosynthesis briefly."}],"stream":true}'

Scegliere i parametri per i modelli di ragionamento

I modelli di ragionamento spesso non supportano parametri comuni per altri modelli di completamento della chat, tra cui temperature, presence_penaltytop_p, e frequency_penalty. Controllare i dettagli del modello nel catalogo dei modelli Foundry prima di aggiungere parametri facoltativi. Impostare un valore max_completion_tokens adeguato, perché sia i token di ragionamento sia i token della risposta finale concorrono al limite.

Usa prompt brevi e diretti. Evitare di chiedere al modello di rivelare una catena di pensieri. Per le conversazioni a più turni, aggiungere la risposta finale anziché il contenuto del ragionamento quando il modello restituisce entrambi.

Gestire le risposte di sicurezza del contenuto

Foundry applica il filtro del contenuto alle distribuzioni supportate. Una richiesta o una risposta può essere bloccata quando viola un criterio di sicurezza del contenuto configurato. Gestite il motivo di conclusione content_filter e gli errori HTTP 400 nella vostra applicazione, mostrate un messaggio utile all'utente e non riprovate lo stesso prompt bloccato senza modificarlo.

{
       "error": {
              "code": "content_filter",
              "message": "The response was filtered due to the prompt triggering a content policy."
       }
}

Per le opzioni di configurazione e controllo, vedere Sicurezza dei contenuti di Azure AI.

Informazioni sui modelli di ragionamento

I modelli di ragionamento raggiungono livelli più elevati di prestazioni in domini come matematica, codifica, scienza, strategia e logistica. Questi modelli usano in modo esplicito una catena di pensiero per esplorare tutti i possibili percorsi prima di generare una risposta. Verificano le loro risposte man mano che li producono, che li aiutano ad arrivare a conclusioni più accurate. Di conseguenza, i modelli di ragionamento potrebbero richiedere un minor numero di richieste di contesto per produrre risultati effettivi.

I modelli di ragionamento producono due tipi di contenuto come output:

Completamenti di ragionamenti
Completamenti dell'output

Entrambi questi completamenti vengono conteggiati per il contenuto generato dal modello. Di conseguenza, contribuiscono ai limiti e ai costi dei token associati al modello. Alcuni modelli, ad esempio DeepSeek-V4-Pro, potrebbero rispondere con il contenuto di ragionamento. Altri, ad esempio o1, generano solo i completamenti.

Modelli di ragionamento rapido

Quando si costruiscono richieste per modelli di ragionamento, tenere in considerazione quanto segue:

Usare istruzioni semplici ed evitare l'uso delle tecniche di concatenazione di pensieri.
Le funzionalità di ragionamento predefinite rendono efficaci semplici richieste zero-shot come i metodi più complessi.
Quando si forniscono contesto o documenti aggiuntivi, ad esempio negli scenari RAG, includere solo le informazioni più rilevanti può impedire al modello di complicare la risposta in modo eccessivo.
I modelli di ragionamento possono supportare l'uso dei messaggi di sistema. Tuttavia, potrebbero non seguirli rigorosamente come altri modelli non basati sul ragionamento.
Quando si creano applicazioni a più turni, è consigliabile aggiungere solo la risposta finale dal modello, senza il relativo contenuto di ragionamento.

Si noti che i modelli di ragionamento possono richiedere più tempo per generare risposte. Usano lunghe catene di ragionamento di pensiero che consentono una risoluzione dei problemi più profonda e più strutturata. Eseguono anche l'auto-verifica per controllare le loro risposte e correggere i loro errori, mostrando così comportamenti emergenti di auto-riflessione.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-08-27