Abilità Prompt GenAI

La competenza GenAI (Generative AI) Prompt esegue una richiesta chat completation su un grande modello linguistico (LLM) distribuito in Azure OpenAI in Foundry Models o Microsoft Foundry. Usa questa abilità per creare nuove informazioni che possano essere indicizzate e memorizzate come contenuti ricercabili.

Ecco alcuni esempi di come la competenza del prompt GenAI possa aiutarti a creare contenuti:

• Verbalizzare le immagini
• Riassumi lunghi passaggi di testo
• Semplificare contenuti complessi
• Esegui qualsiasi altro compito che riesci a esprimere in un prompt

La competenza GenAI Prompt è generalmente disponibile nell'API REST del servizio di ricerca 2026-04-01 e in Azure SDK che rivolgono a questa versione. Questa abilità supporta testo, immagini e contenuti multimodali, come immagini con immagini e testo estratto da file PDF.

Modelli supportati

• È possibile usare qualsiasi modello di inferenza di completamento della chat distribuito in Foundry, ad esempio modelli GPT, DeepSeek-R#, Llama-4-Maverick e Cohere-command-r. Per i modelli GPT specificamente, sono supportati solo gli endpoint API di chat completions. Gli endpoint che utilizzano l'API Azure OpenAI Responses (contenente /openai/responses nell'URI) non sono attualmente compatibili.

• Per la verbalizzazione delle immagini, il modello che si usa per analizzare l'immagine determina quali formati d'immagine sono supportati.

• Per i modelli GPT-5, il parametro temperature non è supportato nello stesso modo dei modelli precedenti. Se definito, deve essere impostato a 1.0, poiché altri valori comporteranno errori.

• La fatturazione si basa sul prezzo del modello che utilizzi.

Prerequisiti

• Una risorsa Azure OpenAI in Foundry Models o Foundry.

• Un modello supportato distribuito alla tua risorsa o progetto.

  • Per Azure OpenAI, copia l'endpoint con il dominio openai.azure.com dalla pagina Keys e Endpoint nel portale Azure. Usa questo endpoint come parametro Uri in questa abilità.

  • Per Foundry, copia l'URI target per il deployment dalla pagina Modelli nel portale Foundry. Usa questo endpoint come parametro Uri in questa abilità.

• L'autenticazione può essere basata su chiavi con una chiave API della tua risorsa OpenAI di Foundry o Azure. Tuttavia, raccomandiamo l'accesso basato sul ruolo utilizzando un'identità gestita da servizio di ricerca assegnata a un ruolo.

  • Su Azure OpenAI, assegna Cognitive Services OpenAI User all'identità gestita.

  • In Foundry assegnare l'utente Foundry all'identità gestita.

    Importante

    I ruoli controllo degli accessi in base al ruolo foundry sono stati rinominati di recente. Foundry User, Foundry Owner, Proprietario accountFoundry e Foundry Project Manager sono stati precedentemente denominati Azure utente di intelligenza artificiale, proprietario dell'intelligenza artificiale Azure, proprietario dell'account Azure ai e Azure ai Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

Limiti dei dati

Parametri della competenza

* Deve essere usata esattamente una delle apiKey, authIdentity, o l'identità assegnata al sistema del servizio.

commonModelParameters Default

Input delle competenze

Output delle competenze

Definizioni di esempio

Riepilogo solo testo

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

Descrizione testo + immagine

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

Ricerca di fatti numerica strutturata

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

Output campione (troncato)

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

Procedure consigliate

• Blocca i documenti lunghi con l'abilità Text Split per rimanere nella finestra contestuale del modello.
• Per indicizzazione ad alto volume, dedicare una distribuzione separata del modello a questa competenza in modo che le quote di token per i carichi di lavoro RAG in tempo di query rimangano inalterati.
• Per minimizzare la latenza, co-localizza il modello e il tuo servizio Azure AI Search nella stessa regione Azure.
• Usa responseFormat.json_schema con GPT-4o per un'estrazione strutturata affidabile e una mappatura più semplice ai campi indicizzati.
• Monitora l'utilizzo dei token e invia richieste di aumento di quota se l'indicizzatore supera i tuoi limiti di Token per Minuto (TPM).

Errori e avvertenze

Considerazioni sulla sicurezza per l'autenticazione dell'identità gestita

Quando la competenza Prompt genAI usa l'autenticazione dell'identità gestita, Azure AI Search ottiene un token di accesso Microsoft Entra per il gruppo di destinatari di Foundry Tools (https://cognitiveservices.azure.com) e lo include nelle richieste inviate all'endpoint specificato da uri. L'autenticazione dell'identità gestita si applica quando authIdentity è impostata o quando apiKey e authIdentity sono vuoti e il servizio usa l'identità assegnata dal sistema.

L'endpoint a cui si uri fa riferimento deve essere la propria Azure risorsa OpenAI o Foundry. I domini supportati sono:

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

sono supportati anche gli endpoint Gestione API di Azure (*.azure-api.netGESTIONE API) e i domini personalizzati che riguardano queste risorse. Poiché un dominio personalizzato o un nome host di Gestione API non può essere verificato solo dal nome, Azure AI Search convalida questi endpoint con un controllo della connettività in tempo reale in fase di configurazione anziché in base alla corrispondenza del dominio. L'utente è responsabile della configurazione e della gestione della relazione tra l'endpoint e la Azure risorsa OpenAI o Foundry sottostante.

Procedure di sicurezza consigliate

Per mantenere una distribuzione sicura, seguire queste procedure:

• Impostare uri solo sugli endpoint di cui si è proprietari e si è attendibili. Preferisce i domini degli strumenti foundry elencati in precedenza. Se si usa un apim o un endpoint di dominio personalizzato, verificare che venga anteriore alla propria risorsa prima di abilitare l'identità gestita. Un nome host attendibile non è una prova di proprietà.
• Applicare il principio del privilegio minimo all'identità gestita usata dal servizio di ricerca:
  • In Azure OpenAI assegnare solo l'utente OpenAI di Servizi cognitivi.
  • In Foundry assegnare solo l'utente Foundry. Evitare di concedere ruoli più ampi.
• Usare Network Security Perimeter (NSP) e endpoint privati o integrazione rete virtuale per limitare gli endpoint che il servizio di ricerca può raggiungere e da quali origini la risorsa di destinazione accetta le richieste.
• Se si usa un'APIM o un endpoint di dominio personalizzato, verificare che il gateway convalide le richieste in ingresso e le inoltra solo al back-end previsto. È anche consigliabile esaminare periodicamente i criteri di accesso.
• Preferisce l'identità gestita rispetto a apiKey. Se si usa apiKey, archiviarlo e ruotarlo in modo sicuro e non incorporarlo nel controllo del codice sorgente. Il servizio rifiuta le configurazioni che impostano sia apiKey che authIdentity.
• Esaminare periodicamente le definizioni del set di competenze, le assegnazioni di ruolo dell'identità gestita e gestione API e le configurazioni di dominio personalizzato per verificare che uri i valori, i controlli di accesso e le autorizzazioni di identità rimangano aggiornati e appropriati. Esaminare le modifiche alla configurazione tramite i processi di gestione delle modifiche e di revisione della sicurezza stabiliti.
• Monitorare Azure log di accesso di OpenAI, Foundry Tools e Foundry, eventi di autenticazione e log di accesso per attività impreviste o non autorizzate.
• Rimuovere competenze, endpoint, assegnazioni di ruolo e chiavi API inutilizzate che non sono più necessarie.

Limitare l'accesso alla configurazione del set di competenze

Gli utenti che possono creare, modificare o eseguire set di competenze controllano sia l'endpoint di destinazione (uri) che la configurazione di autenticazione usata dalla competenza. Poiché la competenza invia un token di identità gestito per il gruppo di destinatari degli strumenti foundry a tale endpoint, limitare queste autorizzazioni agli amministratori attendibili e seguire i processi standard di gestione delle modifiche e di revisione della sicurezza durante la configurazione delle competenze abilitate per l'identità gestita.

Vedere anche

• Azure AI Search indicizzatori integrati
• Vettorizzazione integrata
• Come definire un set di competenze
• Come generare completamento di chat con Azure inferenza del modello AI (Foundry)
• Output strutturati in Azure OpenAI