Habilidade de Prompt GenAI

A habilidade GenAI (IA Generativa) Prompt executa uma solicitação chat completation contra um grande modelo de linguagem (LLM) implantado em Azure OpenAI em Foundry Models ou Microsoft Foundry. Use essa habilidade para criar novas informações que possam ser indexadas e armazenadas como conteúdo pesquisável.

Aqui estão alguns exemplos de como a habilidade do prompt GenAI pode ajudar você a criar conteúdo:

• Verbalizar imagens
• Resuma grandes trechos de texto
• Simplificar conteúdo complexo
• Realize qualquer outra tarefa que você consiga articular em um prompt

A habilidade GenAI Prompt está geralmente disponível na API REST do Serviço de Busca 2026-04-01 e em SDKs do Azure que têm como alvo esta versão. Essa habilidade suporta texto, imagem e conteúdo multimodal, como imagens com imagens e texto extraído de arquivos PDF.

Modelos com suporte

• Você pode usar qualquer modelo de inferência de conclusão de chat implantado no Foundry, como modelos GPT, DeepSeek-R#, Llama-4-Maverick e Cohere-command-r. Para modelos GPT especificamente, apenas os endpoints da API de completação de chat são suportados. Endpoints que usam a API Azure OpenAI Responses (contendo /openai/responses no URI) atualmente não são compatíveis.

• Para verbalização de imagens, o modelo que você usa para analisar a imagem determina quais formatos de imagem são suportados.

• Para modelos GPT-5, o temperature parâmetro não é suportado da mesma forma que os modelos anteriores. Se definido, deve ser definido para 1.0, pois outros valores resultarão em erros.

• A cobrança é baseada no preço do modelo que você usa.

Pré-requisitos

• Um recurso Azure OpenAI em Foundry Models ou Foundry.

• Um modelo suportado implantado no seu recurso ou projeto.

  • Para Azure OpenAI, copie o endpoint com o domínio openai.azure.com da página Keys e Endpoint no portal Azure. Use este endpoint para o Uri parâmetro dessa habilidade.

  • Para o Foundry, copie o URI alvo para a implantação da página de Modelos no portal do Foundry. Use este endpoint para o Uri parâmetro dessa habilidade.

• A autenticação pode ser baseada em chaves com uma chave API do seu recurso Foundry ou Azure OpenAI. No entanto, recomendamos o acesso baseado em função usando uma identidade gerenciada por serviço de busca atribuída a uma função.

  • No Azure OpenAI, atribua Cognitive Services OpenAI User à identidade gerenciada.

  • No Foundry, atribua o Usuário do Foundry à identidade gerenciada.

    Importante

    As funções RBAC da Foundry foram renomeada recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram previamente nomeados Azure Usuário de IA, proprietário de IA Azure, proprietário da conta de IA Azure e Azure Gerente de Project de IA. Você ainda pode ver os nomes anteriores em alguns lugares enquanto a renomeação é distribuída. As IDs de função e as permissões principais não são alteradas pela renomeação.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

Limites de dados

Parâmetros de habilidade

* Exatamente uma das apiKey, authIdentity, ou a identidade atribuída ao sistema do serviço deve ser usada.

commonModelParameters Padrões

Entradas de competências

Resultados de competências

Definições de exemplo

Resumo somente texto

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Summarizer",
  "description": "Summarizes document content.",
  "context": "/document",
  "inputs": [
    { "name": "text", "source": "/document/content" },
    { "name": "systemMessage", "source": "='You are a concise AI assistant.'" },
    { "name": "userMessage", "source": "='Summarize the following text:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "commonModelParameters": { "temperature": 0.3 }
}

Descrição de texto + imagem

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Image Describer",
  "context": "/document/normalized_images/*",
  "inputs": [
    { "name": "image", "source": "/document/normalized_images/*/data" },
    { "name": "imageDetail", "source": "=high" },
    { "name": "systemMessage", "source": "='You are a useful AI assistant.'" },
    { "name": "userMessage", "source": "='Describe this image:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "authIdentity": "11111111-2222-3333-4444-555555555555",
  "responseFormat": { "type": "text" }
}

Localizador numérico estruturado de fatos

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "NumericalFactFinder",
  "context": "/document",
  "inputs": [
    { "name": "systemMessage", "source": "='You are an AI assistant that helps people find information.'" },
    { "name": "userMessage", "source": "='Find all the numerical data and put it in the specified fact format.'"}, 
    { "name": "text", "source": "/document/content" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "responseFormat": {
    "type": "json_schema",
    "jsonSchemaProperties": {
      "name": "NumericalFactObj",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": "{\"facts\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"number\":{\"type\":\"number\"},\"fact\":{\"type\":\"string\"}},\"required\":[\"number\",\"fact\"]}}}",
        "required": [ "facts" ],
        "additionalProperties": false
      }
    }
  }
}

Saída de amostra (truncada)

{
  "response": {
    "facts": [
      { "number": 32.0, "fact": "Jordan scored 32 points per game in 1986-87." },
      { "number": 6.0,  "fact": "He won 6 NBA championships." }
    ]
  },
  "usageInformation": {
    "usage": {
      "completion_tokens": 203,
      "prompt_tokens": 248,
      "total_tokens": 451
    }
  }
}

Práticas recomendadas

• Faça blocos de documentos longos com a habilidade Text Split para permanecer dentro da janela de contexto do modelo.
• Para indexação de alto volume, dedique uma implantação separada do modelo a essa habilidade para que as cotas de tokens para cargas de trabalho RAG em tempo de consulta permaneçam inalteradas.
• Para minimizar a latência, coloque o modelo e seu serviço Pesquisa de IA do Azure  na mesma região do Azure.
• Use responseFormat.json_schema com GPT-4o para extração estruturada confiável e mapeamento mais fácil para campos de índice.
• Monitore o uso dos tokens e envie solicitações de aumento de cota se o indexador saturar seus limites de Tokens por Minuto (TPM).

Erros e avisos

Considerações de segurança para autenticação de identidade gerenciada

Quando a habilidade do Prompt do GenAI usa a autenticação de identidade gerenciada, Pesquisa de IA do Azure  obtém um token de acesso Microsoft Entra para o público-alvo das Ferramentas de Pesquisa (https://cognitiveservices.azure.com) e inclui-o em solicitações enviadas para o ponto de extremidade especificado por uri. A autenticação de identidade gerenciada se aplica quando authIdentity é definida ou quando ambas apiKeyauthIdentity estão vazias e o serviço usa a identidade atribuída pelo sistema.

Espera-se que o ponto de extremidade referenciado seja uri seu próprio Azure recurso OpenAI ou Foundry. Domínios suportados são:

• openai.azure.com
• cognitiveservices.azure.com
• services.ai.azure.com

também há suporte para pontos de extremidade *.azure-api.net e domínios personalizados que estão à frente desses recursos. Como um domínio personalizado ou nome de host APIM não pode ser verificado apenas em seu nome, Pesquisa de IA do Azure  valida esses pontos de extremidade com uma verificação de conectividade dinâmica no momento da configuração e não por correspondência de domínio. Você é responsável por configurar e manter a relação entre o ponto de extremidade e o Azure recurso OpenAI ou Foundry por trás dele.

Práticas de segurança recomendadas

Para ajudar a manter uma implantação segura, siga estas práticas:

• Defina uri apenas como pontos de extremidade que você possui e confie. Prefira os domínios das Ferramentas de Fundimento listados anteriormente. Se você usar um APIM ou um ponto de extremidade de domínio personalizado, confirme se ele está à frente do seu próprio recurso antes de habilitar a identidade gerenciada. Um nome de host de aparência confiável não é prova de propriedade.
• Aplique o princípio de privilégio mínimo à identidade gerenciada usada pelo serviço de pesquisa:
  • No Azure OpenAI, atribua apenas o Usuário openai dos Serviços Cognitivos.
  • No Foundry, atribua apenas o Usuário do Foundry. Evite conceder funções mais amplas.
• Use o NSP (Perímetro de Segurança de Rede) e pontos de extremidade privados ou integração de VNet para restringir quais pontos de extremidade o serviço de pesquisa pode alcançar e de quais fontes o recurso de destino aceita solicitações.
• Se você usar um APIM ou um ponto de extremidade de domínio personalizado, verifique se o gateway valida as solicitações de entrada e encaminha-as apenas para o back-end pretendido. Você também deve examinar suas políticas de acesso periodicamente.
• Prefira a identidade gerenciada em vez de apiKey. Se você usar apiKey, armazene-o e gire-o com segurança e não insira-o no controle do código-fonte. O serviço rejeita configurações que definem ambos apiKey e authIdentity.
• Examine periodicamente definições de conjunto de habilidades, atribuições de função de identidade gerenciada e APIM e configurações de domínio personalizado para confirmar que uri valores, controles de acesso e permissões de identidade permanecem atuais e apropriados. Examine as alterações de configuração por meio dos processos estabelecidos de gerenciamento de alterações e revisão de segurança.
• Monitore Azure Logs de entrada, eventos de autenticação e logs de acesso do OpenAI, Das Ferramentas de Fundiária e do Foundry para atividades inesperadas ou não autorizadas.
• Remova habilidades não utilizados, pontos de extremidade, atribuições de função e chaves de API que não são mais necessárias.

Restringir o acesso à configuração do conjunto de habilidades

Os usuários que podem criar, modificar ou executar conjuntos de habilidades controlam o ponto de extremidade de destino (uri) e a configuração de autenticação usada pela habilidade. Como a habilidade envia um token de identidade gerenciada para o público-alvo das Ferramentas de Pesquisa para esse ponto de extremidade, restrinja essas permissões a administradores confiáveis e siga seus processos padrão de gerenciamento de alterações e revisão de segurança ao configurar habilidades habilitadas para identidade gerenciada.

Consulte também

• Pesquisa de IA do Azure  indexadores embutidos
• Vetorização integrada
• Como definir um conjunto de habilidades
• Como gerar conclusãos de chat com inferência de modelo de IA Azure (Foundry)
• Saídas estruturadas em Azure OpenAI