Habilidade de prompt do GenAI

2025-05-28

Observação

Esse recurso está atualmente em versão prévia pública. Essa visualização é fornecida sem um contrato de nível de serviço e não é recomendada para utilização em produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

A habilidade de Prompt de GenAI (IA Generativa) executa uma solicitação de conclusão de chat em um LLM (Modelo de Linguagem Grande) implantado no Azure AI Foundry ou no Azure OpenAI em Modelos de Descoberta de IA do Azure.

Use esse recurso para criar novas informações que podem ser indexadas e armazenadas como conteúdo pesquisável. Os exemplos incluem verbalizar imagens, resumir passagens maiores, simplificar conteúdo complexo ou qualquer outra tarefa que uma LLM possa executar. A habilidade dá suporte a texto, imagem e conteúdo multimodal, como um PDF que contém texto e imagens. É comum usar essa habilidade combinada com uma habilidade de agrupamento de dados. Os tutoriais a seguir demonstram os cenários de verbalização de imagem com duas técnicas diferentes de agrupamento de dados:

A habilidade do Prompt do GenAI está disponível apenas na API REST 2025-05-01-preview .

Modelos com suporte

Você pode usar qualquer modelo de inferência de conclusão de chat implantado na AI Foundry, como modelos GPT, Deepseek R#, Llama-4-Mavericj, Cohere-command-r e assim por diante.

A cobrança é baseada nos preços do modelo que você usa.

Observação

O serviço de pesquisa se conecta ao seu modelo em um ponto de extremidade público, portanto, não há requisitos de localização de região, mas se você estiver usando uma solução completa do Azure, deverá verificar as regiões do Azure AI Search e as regiões de modelo do Azure OpenAI para encontrar pares adequados, especialmente se você tiver requisitos de residência de dados.

Pré-requisitos

Um modelo de conclusão de chat implantado (por exemplo , gpt-4o ou qualquer modelo de OSS (software de software livre) compatível) no Azure AI Foundry ou no Azure OpenAI.
- Copie o ponto de extremidade de Modelos + Pontos de Extremidade no portal do Foundry ou do subdomínio de recursos do Azure OpenAI (*.openai.azure.com).
- Forneça esse ponto de extremidade no Uri parâmetro de sua definição de habilidade.
A autenticação pode ser baseada em chave com uma chave de API do recurso do Azure AI Foundry ou do Azure OpenAI. No entanto, recomendamos o acesso baseado em função usando uma identidade gerenciada do serviço de pesquisa atribuída a uma função.
- No Azure OpenAI, atribua o Usuário OpenAI dos Serviços Cognitivos à identidade gerenciada.
- Para modelos do AI Foundry, atribua o usuário de IA do Azure.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

Limites de dados

Limite	Anotações
`maxTokens`	O padrão é 1024 se omitido. O valor máximo depende do modelo.
Tempo limite de solicitação	30 segundos (padrão). Substitua com a `timeout` propriedade (`PT##S`).
Imagens	Há suporte para imagens codificadas em base 64 e URLs de imagem. O limite de tamanho depende do modelo.

Parâmetros de habilidades

Propriedade	Tipo	Obrigatório	Anotações
`uri`	corda	Sim	Ponto de extremidade público do modelo implantado.
`apiKey`	corda	Cond.*	Chave secreta para o modelo. Deixe em branco ao usar a identidade gerenciada.
`authIdentity`	corda	Cond.*	ID do cliente de identidade gerenciada atribuída pelo usuário (somente Azure OpenAI). Deixe em branco para usar a identidade atribuída pelo sistema .
`commonModelParameters`	objeto	Não	Controles de geração padrão, como `temperature`, `maxTokens`etc.
`extraParameters`	objeto	Não	Abra o dicionário passado para a API de modelo subjacente.
`extraParametersBehavior`	corda	Não	`"pass-through"` \| `"drop"` \| `"error"` (padrão `"error"`).
`responseFormat`	objeto	Não	Controla se o modelo retorna texto, um objeto JSON de forma livre ou um esquema JSON fortemente tipado. `responseFormat` exemplos de conteúdo: {responseFormat: { type: text }}, {responseFormat: { type: json_object }}, {responseFormat: { type: json_schema }}

* Exatamente um deles apiKeyauthIdentityou a identidade atribuída pelo sistema do serviço deve ser usada.

`commonModelParameters` Padrões

Parâmetro	Padrão
`model`	(padrão de implantação)
`frequencyPenalty`	0
`presencePenalty`	0
`maxTokens`	1024
`temperature`	0,7
`seed`	zero
`stop`	zero

Entradas de habilidades

Nome de entrada	Tipo	Obrigatório	Descrição
`systemMessage`	corda	Sim	Instrução no nível do sistema (por exemplo: "Você é um assistente útil".
`userMessage`	corda	Sim	Prompt do usuário.
`text`	corda	Não	Texto opcional acrescentado a `userMessage` (cenários somente texto).
`image`	cadeia de caracteres (URL de dados base 64)	Não	Adiciona uma imagem ao prompt (somente modelos multimodal).
`imageDetail`	cadeia de caracteres (`low` \| `high` \| `auto`)	Não	Dica de fidelidade para modelos multimodal do Azure OpenAI.

Saídas de habilidades

Nome de saída	Tipo	Descrição
`response`	string ou objeto JSON	Saída do modelo no formato solicitado por `responseFormat.type`.
`usageInformation`	Objeto JSON	Contagens de token e eco de parâmetros de modelo.

Definições de exemplo

Resumo somente texto

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Summarizer",
  "description": "Summarizes document content.",
  "context": "/document",
  "timeout": "PT30S",
  "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 }
}

Texto + descrição da 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 de fatos numérico estruturado

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

Práticas recomendadas

Particione documentos longos com a habilidade de Divisão de Texto para permanecer dentro da janela de contexto do modelo.
Para indexação de alto volume, dedique uma implantação de modelo separada a essa habilidade para que as cotas de token para cargas de trabalho RAG em tempo de consulta permaneçam não afetadas.
Para minimizar a latência, localize o modelo e o serviço do Azure AI Search 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 do token e envie solicitações de aumento de cota se o indexador saturar seus limites de Tokens por Minuto (TPM).

Erros e avisos

Condição	Resultado
Ausente ou inválido `uri`	Erro
Nenhum método de autenticação especificado	Erro
Ambos `apiKey` e `authIdentity` fornecidos	Erro
Modelo sem suporte para prompt multimodal	Erro
A entrada excede o limite do token de modelo	Erro
O modelo retorna JSON inválido para `json_schema`	Aviso – cadeia de caracteres bruta retornada em `response`