Perícia de Prompt GenAI

A competência GenAI (IA Generativa) Prompt executa um pedido chat completion contra um grande modelo de linguagem (LLM) implementado em Azure OpenAI em Foundry Models ou Microsoft Foundry. Use esta competência para criar nova informação que possa ser indexada e armazenada como conteúdo pesquisável.

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

• Verbalizar imagens
• Resumir grandes passagens de texto
• Simplificar conteúdos complexos
• Realiza qualquer outra tarefa que consigas articular num prompt

A competência GenAI Prompt está geralmente disponível na API REST do Serviço de Pesquisa 2026-04-01 e em SDKs do Azure que visam esta versão. Esta competência suporta texto, imagem e conteúdos multimodais, como imagens com visuais e texto extraído de ficheiros PDF.

Modelos suportados

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

• Para a verbalização de imagens, o modelo que utiliza para analisar a imagem determina quais os formatos de imagem 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 faturação baseia-se no preço do modelo que utiliza.

Pré-requisitos

• Um recurso Azure OpenAI em Foundry Models ou Foundry.

• Um modelo suportado implementado 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. Usa este endpoint para o Uri parâmetro desta competência.

  • Para o Foundry, copie o URI alvo para a implementação a partir da página de Modelos no portal do Foundry. Usa este endpoint para o Uri parâmetro desta competência.

• 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 utilizando uma identidade gerida por serviço de pesquisa atribuída a uma função.

  • No Azure OpenAI, atribui Cognitive Services OpenAI User à identidade gerida.

  • No Foundry, atribui o Utilizador do Foundry à identidade gerida.

    Importante

    Os papéis RBAC da Fundição foram recentemente renomeados. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager foram anteriormente nomeados Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. Ainda podes ver os nomes anteriores em alguns sítios enquanto a mudança de nome é lançada. Os IDs de função e as permissões do núcleo mantêm-se inalterados com a mudança de nome.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

Limites de dados

Parâmetros de habilidade

* Deve ser usada exatamente uma de apiKey, authIdentity, ou a identidade atribuída pelo sistema do serviço.

commonModelParameters Padrões

Entradas de habilidades

Resultados em termos de competências

Definições de exemplo

Sumarização 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" }
}

Descobridor numérico estruturado de factos

{
  "@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 exemplo (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
    }
  }
}

Melhores práticas

• 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 implementação de modelo separada a esta competência, de modo a que as quotas de tokens para cargas de trabalho RAG em tempo de consulta permaneçam inalteradas.
• Para minimizar a latência, coloque o modelo e o seu serviço Pesquisa de IA do Azure na mesma região Azure.
• Use responseFormat.json_schema com GPT-4o para extração estruturada fiável e mapeamento mais fácil para campos de índice.
• Monitorize a utilização dos tokens e submeta pedidos de aumento de quota se o indexador saturar os seus limites de Tokens por Minuto (TPM).

Erros e avisos

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

Quando a competência GenAI Prompt utiliza autenticação de identidade gerida, o Pesquisa de IA do Azure obtém um token de acesso Microsoft Entra para a audiência do Foundry Tools (https://cognitiveservices.azure.com) e inclui-o em pedidos enviados ao endpoint especificado por uri. A autenticação de identidade gerida aplica-se quando authIdentity está definida, ou quando ambos apiKey e authIdentity estão vazios e o serviço utiliza a identidade atribuída pelo sistema.

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

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

API Management do Azure (APIM), endpoints (*.azure-api.net) e domínios personalizados que antecedem estes recursos também são suportados. Como um domínio personalizado ou nome de host APIM não pode ser verificado apenas pelo seu nome, o Pesquisa de IA do Azure valida estes endpoints com uma verificação de conectividade ao vivo no momento da configuração, em vez de por correspondência de domínio. És responsável por configurar e manter a relação entre o endpoint e o recurso Azure 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 para endpoints que possua e em quem confia. Prefiro os domínios Foundry Tools listados anteriormente. Se usar um APIM ou endpoint de domínio personalizado, confirme que ele antecipa o seu próprio recurso antes de ativar a identidade gerida. Um nome de anfitrião com aparência confiável não é prova de propriedade.
• Aplique o princípio do menor privilégio à identidade gerida usada pelo serviço de pesquisa:
  • No Azure OpenAI, atribui apenas Cognitive Services OpenAI User.
  • No Foundry, atribui apenas o Utilizador do Foundry. Evite atribuir cargos mais amplos.
• Use o Perímetro de Segurança de Rede (NSP) e endpoints privados ou integração com VNet para restringir quais os endpoints que o serviço de pesquisa pode alcançar e de que fontes o recurso alvo aceita pedidos.
• Se usar um endpoint APIM ou de domínio personalizado, certifique-se de que o gateway valida os pedidos de entrada e os encaminha apenas para o backend pretendido. Também deve rever periodicamente as suas políticas de acesso.
• Prefira identidade gerida em vez de apiKey. Se usares apiKey, guarda e roda de forma segura e não o incorpores no controlo de versão. O serviço rejeita configurações que definem tanto apiKey como authIdentity.
• Revise periodicamente definições de conjuntos de competências, atribuições de papéis de identidade geridas, APIM e configurações de domínio personalizado para confirmar que uri os valores, controlos de acesso e permissões de identidade permanecem atuais e apropriados. Revise as alterações de configuração através dos seus processos estabelecidos de gestão de alterações e revisão de segurança.
• Monitorize os registos de início de sessão do Azure OpenAI, Foundry Tools e Foundry, eventos de autenticação e registos de acesso para atividades inesperadas ou não autorizadas.
• Remova competências não utilizadas, endpoints, atribuições de funções e chaves de API que já não são necessárias.

Restringir o acesso à configuração de competências

Os utilizadores que podem criar, modificar ou executar conjuntos de competências controlam tanto o endpoint de destino (uri) como a configuração de autenticação usada pela competência. Como a competência envia um token de identidade gerida para o público das Foundry Tools para esse endpoint, restrinja essas permissões a administradores de confiança e siga os seus processos padrão de gestão de alterações e revisão de segurança ao configurar competências habilitadas para identidade gerida.

Ver também

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