Usar modelos de raciocínio com modelos de Microsoft Foundry

Os modelos de raciocínio usam computação extra para resolver problemas complexos antes de retornar uma resposta. Este artigo mostra como chamar um modelo de raciocínio que não é da OpenAI, DeepSeek-V4-Pro, usando a API Chat Completions da OpenAI a partir de um projeto no Foundry.

Pré-requisitos

Uma assinatura do Azure.
Um projeto de fundição. Esse tipo de projeto é gerenciado sob um recurso Foundry. Se você não tiver um projeto do Foundry, consulte Criar um projeto para o Microsoft Foundry.
URL do endpoint do projeto do Foundry, que está no formato https://YOUR-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR_PROJECT_NAME.
Um modelo de raciocínio implementado. Este artigo usa DeepSeek-V4-Pro; substitua o nome do modelo pelo nome da implantação quando necessário.
O SDK ou as ferramentas de linha de comando para o idioma selecionado. Para C#, use o SDK do .NET 10. Os exemplos de C# são testados com os OpenAI pacotes 2.13.0 e Azure.Identity 1.21.0.
Permissão para acessar o projeto e a implantação do modelo. Para autenticação sem chave, entre com uma identidade que tenha o acesso necessário ao projeto do Foundry.

Usar o kit de início do modelo de IA

Os exemplos no kit inicial de modelo de IA usam clientes padrão da OpenAI com um endpoint de projeto do Foundry e o caminho /openai/v1. O kit inicial inclui um exemplo completo para um modelo de raciocínio DeepSeek. Seus exemplos atuais usam a API de Respostas. Os exemplos neste artigo usam a API Chat Completions para implantações que expõem essa API.

Configurar o cliente

Use Microsoft Entra ID para autenticar o cliente OpenAI. O escopo do token para o endpoint do projeto Foundry é https://ai.azure.com/.default. O ponto de extremidade deve ser o ponto de extremidade do projeto, não o ponto de extremidade do recurso e a URL base do cliente deve acrescentar /openai/v1.

Instalar openai e azure-identity bibliotecas.

pip install --upgrade openai azure-identity

Use o código a seguir para configurar o objeto cliente OpenAI na rota do projeto.

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,
)

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

Use o seguinte código para configurar o objeto cliente OpenAI na rota do projeto:

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,
});

Adicione openai-java e azure-identity , em seguida, configure o objeto cliente OpenAI na rota do projeto. O seguinte padrão de cliente usa o SDK do Java OpenAI e o provedor de 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();

Instale os pacotes OpenAI e Azure.Identity:

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

Use o código a seguir para configurar o objeto cliente OpenAI na rota do projeto.

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") });

Obtenha um token Entra para o escopo https://ai.azure.com/.default e envie-o como um token bearer. Nenhum api-version parâmetro de consulta é necessário para /openai/v1.

export AZURE_AI_AUTH_TOKEN="<entra-token>"

Criar uma completação básica de chat

Envie uma mensagem de usuário para o modelo de raciocínio implantado. A resposta contém a resposta final em message.content. Dependendo do modelo, a resposta também pode conter conteúdo de raciocínio em 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?"}]
       }'

Ler conteúdo de raciocínio

Alguns modelos de raciocínio que não são da OpenAI retornam um campo reasoning_content junto com o content final. O conteúdo de raciocínio pode ser extenso e é contabilizado no uso de tokens. Não adicione-o ao histórico de mensagens de uma conversa de vários turnos, a menos que a documentação do modelo exija especificamente. Armazene ou exiba-o somente quando seu aplicativo precisar e trate-o como saída de modelo em vez de uma explicação verificada.

Para modelos que não retornam reasoning_content, use o valor final content . O campo depende do modelo e não está disponível para todos os modelos de raciocínio.

Transmitir uma conclusão

Defina stream como true para receber eventos enviados pelo servidor à medida que o modelo gera a saída. O conteúdo do raciocínio e o conteúdo da resposta final podem chegar em campos delta diferentes. Os exemplos a seguir imprimem o conteúdo da resposta final à medida que ele chega.

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}'

Escolher parâmetros para modelos de raciocínio

Os modelos de raciocínio geralmente não dão suporte a parâmetros comuns para outros modelos de conclusão de chat, incluindo temperature, top_pe presence_penaltyfrequency_penalty. Verifique os detalhes do modelo no catálogo de modelos do Foundry antes de adicionar parâmetros opcionais. Defina um valor max_completion_tokens suficiente, pois os tokens de raciocínio e os tokens de resposta final contam para esse limite.

Use prompts curtos e diretos. Evite solicitar que o modelo revele sua cadeia de raciocínio. Para conversas de vários turnos, acrescente a resposta final em vez do conteúdo de raciocínio quando o modelo retornar ambos.

Gerenciar respostas de segurança de conteúdo

A Foundry aplica a filtragem de conteúdo a implantações com suporte. Uma solicitação ou resposta pode ser bloqueada quando viola uma política de segurança de conteúdo configurada. Trate o motivo de término content_filter e os erros HTTP 400 no seu aplicativo, exiba uma mensagem útil ao usuário e não reenvie o mesmo prompt bloqueado sem alterações.

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

Para obter opções de configuração e controle, consulte Segurança de Conteúdo de IA do Azure.

Sobre modelos de raciocínio

Os modelos de raciocínio atingem níveis mais altos de desempenho em domínios como matemática, codificação, ciência, estratégia e logística. Esses modelos usam explicitamente uma cadeia de pensamento para explorar todos os caminhos possíveis antes de gerar uma resposta. Eles verificam suas respostas à medida que as produzem, o que os ajuda a chegar a conclusões mais precisas. Como resultado, os modelos de raciocínio podem exigir menos solicitações de contexto para produzir resultados eficazes.

Os modelos de raciocínio produzem dois tipos de conteúdo como saídas:

Conclusões de raciocínio
Conclusões de saída

Ambos os completamentos contam para o conteúdo gerado pelo modelo. Portanto, eles contribuem para os limites de token e os custos associados ao modelo. Alguns modelos, como DeepSeek-V4-Pro, podem responder com o conteúdo do raciocínio. Outros, como o1, geram apenas as conclusões.

Modelos de raciocínio de prompt

Ao criar solicitações para modelos de raciocínio, leve o seguinte em consideração:

Use instruções simples e evite usar técnicas de cadeia de pensamento.
Os recursos internos de raciocínio tornam os prompts de zero-shot simples tão eficazes quanto métodos mais complexos.
Ao fornecer contexto ou documentos adicionais, como em cenários RAG, incluir apenas as informações mais relevantes pode ajudar a impedir que o modelo complique demais sua resposta.
Modelos de raciocínio podem dar suporte ao uso de mensagens do sistema. No entanto, eles podem não segui-los tão estritamente quanto outros modelos não baseados em raciocínio.
Ao criar aplicativos de várias rodadas, considere acrescentar apenas a resposta final do modelo, sem seu conteúdo de raciocínio.

Observe que os modelos de raciocínio podem levar mais tempo para gerar respostas. Eles usam cadeias de raciocínio longas de pensamento que permitem uma solução de problemas mais profunda e estruturada. Eles também executam a auto-verificação para verificar suas respostas e corrigir seus erros, mostrando assim comportamentos auto-reflexivos emergentes.

Comentários

Esta página foi útil?

Last updated on 2026-08-27