Implantar e usar modelos do Grok no Microsoft Foundry

Os modelos Grok da SpaceXAI estão disponíveis como Foundry Models vendidos pelo Azure. Use grok-4.7 para codificação, extração de dados, resumo e aplicações agênticas. Esse modelo de disponibilidade geral dá suporte a entrada multimodal (texto e imagem), chamada de ferramenta e raciocínio avançado, com uma janela de contexto de até 500.000 tokens.

Neste artigo, você aprenderá como:

  • Implante o Grok 4.7 no Microsoft Foundry.
  • Autentique usando Microsoft Entra ID ou uma chave de API.
  • Gere saídas com as APIs Chat Completions e Responses.
  • Use níveis de esforço de raciocínio configuráveis.
  • Chame ferramentas com invocação de funções.
  • Transmitir respostas.
  • Solucione problemas de erros comuns.

Pré-requisitos

Antes de começar, você precisa de:

  • Uma assinatura do Azure com uma forma de pagamento válida. Se você não tiver uma assinatura do Azure, crie uma conta paga do Azure.

  • Acesso ao Microsoft Foundry com permissões apropriadas para criar e gerenciar recursos.

  • Um projeto do Microsoft Foundry em uma região com suporte para implantação do Grok 4.7. Para obter mais informações, consulte tipos e regiões de implantação com suporte.

  • A função Colaborador de Serviços Cognitivos no recurso Foundry, para implantar modelos. Para obter mais informações, consulte Funções do Azure RBAC.

  • Um método de autenticação: Microsoft Entra ID (recomendado) ou uma chave de API.

  • Instale as dependências necessárias para executar os exemplos com autenticação do Microsoft Entra ID.

    pip install openai azure-identity

Modelos Grok disponíveis no Foundry

Os modelos Foundry oferecidos pelo Azure incluem os seguintes modelos Grok da SpaceXAI.

Modelo Versão de modelo Tipo de API
grok-4.7 1 Conclusões de chat, respostas
grok-4.6 (versão prévia) 1 Conclusões de chat, respostas
grok-4.3 (versão prévia) 1 Conclusões de chat, respostas
grok-4-20-reasoning (versão prévia) 1 Conclusões de chat, respostas
grok-4-20-non-reasoning (versão prévia) 1 Conclusões de chat, respostas
grok-4.1-fast-reasoning 1 Conclusões de chat, respostas
grok-4.1-fast-non-reasoning 1 Conclusões de chat, respostas
grok-4 1 1 Conclusões de chat, respostas
grok-code-fast-1 1 1 Conclusões de chat, respostas

1O registro é necessário para acessogrok-code-fast-1 e grok-4.

Este artigo se concentra em grok-4.7. Para obter detalhes completos dos recursos de todos os modelos Grok, consulte modelos SpaceXAI comercializados pela Azure.

Note

Os modelos do SpaceXAI Grok em disponibilidade geral a partir do Grok 4.7 estão disponíveis por, no mínimo, seis meses. Para ver as datas de desativação específicas de cada modelo, consulte o cronograma de desativação do modelo.

Implantar o Grok 4.7

Para implantar o Grok 4.7, siga as instruções em Implantar modelos do Microsoft Foundry no portal do Foundry e selecione o modelo grok-4.7 a ser implantado.

Como alternativa, implante o modelo usando o CLI do Azure conforme mostrado no código a seguir.

Substitua <ACCOUNT_NAME>, <RESOURCE_GROUP> e <DEPLOYMENT_NAME> por seus valores.

Defina <DEPLOYMENT_SKU> como o nome da SKU para o tipo de implantação escolhido. Verifique as tabelas de disponibilidade da região para os tipos de implantação e regiões atualmente disponíveis.

az cognitiveservices account deployment create \
  --name <ACCOUNT_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --deployment-name <DEPLOYMENT_NAME> \
  --model-name "grok-4.7" \
  --model-format "xAI" \
  --model-version "1" \
  --sku-name "<DEPLOYMENT_SKU>" \
  --sku-capacity 1

Referência:az cognitiveservices account deployment create

Para saber mais sobre o fluxo de trabalho de implantação por CLI, consulte Adicionar e configurar modelos no Foundry Models.

Gerar saída com a API Chat Completions

Use a API Chat Completions para enviar mensagens para o Grok 4.7. O valor model é o nome da sua implantação, não o nome do modelo subjacente.

Defina as variáveis de ambiente a seguir. O endpoint tem a forma https://<resource-name>.services.ai.azure.com.

export AZURE_ENDPOINT="<your-foundry-resource-endpoint>"
export AZURE_ENTRA_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken --output tsv)
export DEPLOYMENT_NAME="<your-deployment-name>"

Se você não instalou os pacotes openai e azure-identity na seção Pré-requisitos, instale-os agora usando seu gerenciador de pacotes, como o pip:

pip install --upgrade openai azure-identity

Use o Microsoft Entra ID para autenticar e gerar uma conclusão de chat:

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

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url=f"{os.environ['AZURE_ENDPOINT']}/openai/v1",
    api_key=token_provider,
)

response = client.chat.completions.create(
    model=os.environ["DEPLOYMENT_NAME"],
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Summarize the key benefits of an agentic coding workflow."},
    ],
    reasoning_effort="high",  # Options: "low", "medium", "high", "xhigh" (default "high").
)

print(response.choices[0].message.content)

Para usar uma chave de API, passe-a diretamente como api_key:

client = OpenAI(
    base_url=f"{os.environ['AZURE_ENDPOINT']}/openai/v1",
    api_key=os.environ["AZURE_API_KEY"],
)

Gerar uma resposta com a API de Respostas

O Grok 4.7 também dá suporte à Responses API, que oferece uma interface simplificada para interações com vários turnos e orquestração de ferramentas internas.

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

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url=f"{os.environ['AZURE_ENDPOINT']}/openai/v1",
    api_key=token_provider,
)

response = client.responses.create(
    model=os.environ["DEPLOYMENT_NAME"],
    instructions="You are a helpful assistant.",
    input="What are the top 3 benefits of an agentic coding workflow? Be concise.",
    reasoning={
        "effort": "high"  # Options: "low", "medium", "high" (default "high").
    },
)

print(response.output_text)

Use a chamada de funções e ferramentas

O Grok 4.7 dá suporte à chamada de função, usando a Chat Completions API e a API de Respostas. Use a chamada de função quando seu aplicativo precisar do modelo para selecionar uma ferramenta, fornecer argumentos estruturados ou coordenar várias etapas.

API de Conclusões de Chat

{
  "model": "<deployment-name>",
  "messages": [
    { "role": "user", "content": "What's the weather in San Francisco today?" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get the current weather for a city.",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    }
  ]
}

API de Respostas

Para a API Responses, o payload difere da API Chat Completions: passe a conversa no array input utilizando partes de conteúdo tipadas e defina cada ferramenta com os campos de função no nível superior do objeto da ferramenta.

{
  "model": "<deployment-name>",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "What's the weather in San Francisco today?"
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get the current weather for a city.",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string" }
        },
        "required": ["city"]
      }
    }
  ]
}

Respostas em fluxo

Defina stream como true para receber a resposta de forma incremental, em vez de aguardar a resposta completa. O streaming é útil para interfaces de chat e tarefas de longa execução, em que o tempo para o primeiro token importa mais do que a latência total.

API de Conclusões de Chat

stream = client.chat.completions.create(
    model=os.environ["DEPLOYMENT_NAME"],
    messages=[
        {"role": "user", "content": "Count from 1 to 5, one per line."}
    ],
    stream=True,
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)

API de Respostas

stream = client.responses.create(
    model=os.environ["DEPLOYMENT_NAME"],
    input="Count from 1 to 5, one per line.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Quando usar o Grok 4.7

Use o Grok 4.7 para cargas de trabalho corporativas complexas que exigem raciocínio, uso de ferramentas e execução de várias etapas. O Grok 4.7 dá suporte a codificação, fluxos de trabalho agênticos, solução de problemas técnicos e aplicações de trabalho intelectual que se beneficiam do raciocínio sustentado em tarefas estendidas.

Os casos de uso comuns incluem:

  • Aplicações agênticas: use chamada de ferramentas e raciocínio para planejar tarefas, selecionar ferramentas, coordenar fluxos de trabalho com várias etapas e gerar saídas estruturadas.
  • Engenharia de software: suporte à geração de código, compreensão de código, depuração, análise em nível de repositório, geração de teste e fluxos de trabalho complexos de engenharia de software.
  • Trabalho e pesquisa de conhecimento: analisar informações, sintetizar descobertas, gerar relatórios, resumir grandes volumes de conteúdo e dar suporte a tarefas com uso intensivo de pesquisa.
  • Engenharia e fluxos de trabalho técnicos: auxiliar na resolução de problemas técnicos, análise de engenharia, design de procedimento e outras tarefas de raciocínio estruturadas.
  • Automação empresarial: Capacite assistentes corporativos e a automação de fluxos de trabalho que transformam informações em entregáveis de negócios acionáveis, como relatórios, apresentações, planilhas e recomendações.

Endpoints de API

Depois de implantar o Grok 4.7, chame um dos seguintes pontos de extremidade em seu recurso do Foundry:

  • Conclusão de Conversa: https://<resource-name>.services.ai.azure.com/openai/v1/chat/completions
  • Respostas: https://<resource-name>.services.ai.azure.com/openai/v1/responses

Para autenticar, você precisa do endpoint do recurso e de um token do Microsoft Entra ID ou de uma chave de API. Encontre esses valores na seção Chaves e Ponto de Extremidade do recurso no portal do Azure ou na página de detalhes da implantação no portal do Foundry.

Parâmetros de solicitação

Parameter Tipo Obrigatório Description
model cadeia Yes O nome da sua implantação do Microsoft Foundry.
messages matriz Sim, para Chat Completions As mensagens de conversa a serem enviadas para o modelo.
input cadeia de caracteres ou matriz Sim, para respostas. A entrada para o modelo.
instructions cadeia Não Somente respostas. Prompt de sistema para a API Responses.
tools matriz Não Definições de função que o modelo pode chamar.
stream boolean Não Quando true, fornece a resposta como um fluxo de eventos enviados pelo servidor. Usa false como padrão.
reasoning_effort cadeia Não Somente Completações de Chat. Controla a quantidade de raciocínio que o modelo executa. Um de low, medium, highou xhigh. Usa high como padrão.
reasoning objeto Não Somente respostas. Configuração de raciocínio. Definir effort como low, mediumou high. Usa high como padrão.
max_completion_tokens inteiro Não Somente Completações de Chat. Um limite superior para tokens gerados, incluindo tokens de raciocínio.
max_output_tokens inteiro Não Somente respostas. Um limite superior para tokens gerados, incluindo tokens de raciocínio.

Para obter mais informações sobre a API de Respostas, consulte Usar a API de Respostas Azure OpenAI. Para obter mais informações sobre a API de Conclusões de Chat, consulte Trabalhar com modelos de conclusão de chat.

Formato da resposta

O formato de resposta depende de qual API você chama. O Grok 4.7 retorna um objeto compatível com OpenAI para a API de Conclusões de Chat e a API de Respostas.

API de Conclusões de Chat

Uma resposta bem-sucedida de Chat Completions inclui a mensagem do assistente nas opções de resposta.

Field Tipo Description
choices[].message.content cadeia A resposta do assistente. Nulo quando o modelo retorna chamadas de ferramenta.
choices[].message.tool_calls matriz Chamadas de ferramentas de função solicitadas pelo modelo.
choices[].finish_reason cadeia Por que a geração parou. Normalmente stop (conclusão normal), tool_calls (o modelo solicitou uma ferramenta) ou length (atingiu o limite do token).
usage.prompt_tokens inteiro O número de tokens no prompt de entrada.
usage.completion_tokens inteiro O número de tokens gerados, incluindo tokens de raciocínio.
usage.total_tokens inteiro O número total de tokens usados.

O exemplo a seguir mostra uma resposta do Chat Completions que contém uma chamada de função.

{
  "id": "<completion-id>",
  "object": "chat.completion",
  "created": 1785277080,
  "model": "<deployment-name>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"San Francisco\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 87,
    "completion_tokens": 41,
    "total_tokens": 128
  }
}

API de Respostas

Uma chamada de API de Respostas bem-sucedida retorna um response objeto. Em vez de uma choices matriz, a saída do modelo é uma matriz ordenada output de itens tipados, como message, function_calle reasoning itens.

Field Tipo Description
output matriz Uma matriz ordenada de itens de conteúdo que o modelo gerou, como message, function_callou reasoning itens.
output_text cadeia Uma propriedade de conveniência do SDK que agrega o texto dos itens de mensagem de saída.
output[].content[].text cadeia O texto de assistência dentro de um item de saída message.
status cadeia O status da resposta, como completed, incompleteou failed.
usage.input_tokens inteiro O número de tokens na entrada.
usage.output_tokens inteiro O número de tokens gerados, incluindo tokens de raciocínio.
usage.total_tokens inteiro O número total de tokens usados.

O exemplo a seguir mostra um objeto de API de Respostas para uma resposta de texto.

{
  "id": "resp_<id>",
  "object": "response",
  "created_at": 1785277080,
  "status": "completed",
  "model": "<deployment-name>",
  "output": [
    {
      "type": "message",
      "id": "msg_<id>",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "An agentic coding workflow plans tasks, selects tools, and executes multiple steps with minimal supervision.",
          "annotations": []
        }
      ]
    }
  ],
  "output_text": "An agentic coding workflow plans tasks, selects tools, and executes multiple steps with minimal supervision.",
  "usage": {
    "input_tokens": 36,
    "output_tokens": 128,
    "total_tokens": 164
  }
}

Quando o modelo solicita uma ferramenta, a output matriz contém um function_call item em vez de um message item.

{
  "id": "resp_<id>",
  "object": "response",
  "created_at": 1785277080,
  "status": "completed",
  "model": "<deployment-name>",
  "output": [
    {
      "type": "function_call",
      "id": "fc_<id>",
      "call_id": "call_abc123",
      "name": "get_weather",
      "arguments": "{\"city\":\"San Francisco\"}",
      "status": "completed"
    }
  ],
  "output_text": "",
  "usage": {
    "input_tokens": 87,
    "output_tokens": 41,
    "total_tokens": 128
  }
}

Limites de token e janela de contexto

O Grok 4.7 tem uma janela de contexto de 500.000 tokens.

Tanto a entrada quanto a saída gerada contam para a janela de contexto:

  • Tokens de entrada: as mensagens (Chat Completions) ou entrada (Responses) em sua solicitação podem conter até 500.000 tokens.
  • Tokens de saída: max_completion_tokens (Chat Completions) ou max_output_tokens (Responses) delimita a resposta gerada, incluindo tokens de raciocínio. A saída usa o orçamento de contexto restante após a entrada.
  • Total: os tokens de entrada e saída devem caber dentro da janela de contexto de 500.000 tokens. Se uma solicitação exceder a janela de contexto, ela falhará.

Para obter as taxas atuais e os detalhes de cobrança, consulte os preços do modelo grok.

Tipos e regiões de implantação com suporte

Para os tipos de implantação atuais e regiões disponíveis para modelos grok, consulte a disponibilidade de região para modelos de fundimento vendidos por Azure.

Cotas e limites de API

Os limites de taxa da implantação dependem da capacidade configurada e da cota alocada. Para as cotas de TPM (tokens atuais por minuto) e as solicitações correspondentes por minuto (RPM), consulte as cotas do Grok 4.7.

Você pode solicitar mais cota, se necessário. Para obter mais informações, consulte Solicitar aumentos para os limites padrão.

Troubleshoot

Use a tabela a seguir para identificar erros e resoluções comuns.

Error Causa possível Resolução
400 Solicitação Inválida Forma de solicitação inválida ou parâmetro sem suporte. Valide o corpo da solicitação em relação ao contrato de API e verifique os parâmetros com suporte.
401 Não autorizado Chave de API inválida, um token expirado ou um cabeçalho de autenticação ausente ou incorreto. Verifique sua credencial, o escopo do token e o cabeçalho (api-key para obter chaves de API, Authorization: Bearer para Microsoft Entra ID).
403 Proibido Você está autenticado, mas não tem permissão para acessar o modelo solicitado. Verifique sua atribuição de função e o acesso ao modelo.
404 Não Encontrado Nome de endpoint ou de implantação incorreto, ou o recurso referenciado não foi encontrado. Verifique o endpoint e o nome da implantação no Microsoft Foundry.
429 Número excessivo de solicitações Você excedeu o limite de taxa. Tente de novo com um período de espera (backoff), ou solicite um aumento de cota, se disponível.
500 Erro interno do servidor Ocorreu um erro do lado do servidor ou configuração incorreta. Tente de novo com um período de espera. Se o problema persistir, verifique a integridade do serviço e as diretrizes de suporte.

Considerações sobre IA responsável

Antes de usar o Grok 4.7 em um aplicativo, avalie o modelo para o cenário pretendido. Siga estas práticas recomendadas:

  • Valide o comportamento do modelo em prompts realistas.
  • Teste a qualidade, a segurança e a confiabilidade específicas da tarefa.
  • Use a supervisão humana e a validação de especialistas em domínio para fluxos de trabalho de alto impacto.
  • Registre e monitore falhas de acordo com seus requisitos de aplicativo.
  • Aplique o monitoramento adequado de segurança e abuso de conteúdo.

Não use o Grok 4.7 para decisões autônomas de alto risco em sistemas de medicina, direito, finanças ou segurança crítica sem supervisão humana e validação de especialistas em domínio.

Para obter avaliações de funcionalidade e segurança, consulte o cartão de modelo do Grok 4.7.

Os modelos Grok no Microsoft Foundry disponibilizam uma interface de API de Chat Completions e Responses compatível com a OpenAI. Para obter o esquema completo de solicitação e resposta, consulte a referência da API de Conclusões e Respostas de Chat do SpaceXAI. Alguns parâmetros descritos lá, como opções de pesquisa ao vivo, não se aplicam a implantações hospedadas em Azure.

Conteúdo relacionado

  • Última atualização em