Dovednost GenAI Prompt

Dovednost GenAI (Generative AI) Prompt vykonává požadavek chat completion proti velkému jazykovému modelu (LLM) nasazenému v Azure OpenAI ve Foundry Models nebo Microsoft Foundry. Tuto dovednost využijte k vytváření nových informací, které lze indexovat a ukládat jako vyhledávatelný obsah.

Zde je několik příkladů, jak vám může dovednost GenAI prompt pomoci vytvářet obsah:

• Slovní ztěžování obrázků
• Shrnout rozsáhlé textové pasáže
• Zjednodušte složitý obsah
• Vykonejte jakýkoli jiný úkol, který dokážete v zadání vyjádřit

Dovednost GenAI Prompt je obecně dostupná v REST API 2026-04-01 Search Service REST API a také v Sady Azure SDK, které cílí na tuto verzi. Tato dovednost podporuje text, obrázky a multimodální obsah, jako jsou obrázky s vizuály a textem extrahovaným z PDF souborů.

Podporované modely

• Můžete použít jakýkoli model odvozování chatu nasazený v Foundry, například modely GPT, DeepSeek-R#, Llama-4-Maverick a Cohere-command-r. Konkrétně u GPT modelů jsou podporovány pouze endpointy API pro dokončení chatu. Koncové zařízení používající Azure OpenAI Responses API (obsahující /openai/responses v URI) momentálně nejsou kompatibilní.

• Pro verbalizaci obrázků model, který používáte k analýze, určuje, jaké formáty obrázků jsou podporovány.

• U modelů GPT-5 není tento temperature parametr podporován stejným způsobem jako předchozí modely. Pokud je definován, musí být nastaven na 1.0, protože jiné hodnoty povedou k chybám.

• Fakturace je založena na cenách modelu, který používáte.

Předpoklady

• Zdroj Azure OpenAI v prostředku Foundry Models nebo Foundry.

• Podporovaný model nasazený na vašem zdroji nebo projektu.

  • Pro Azure OpenAI zkopírujte endpoint s doménou openai.azure.com ze stránky Keys and Endpoint v Azure portálu. Použijte tento koncový bod pro Uri parametr v této dovednosti.

  • Pro Foundry zkopírujte cílové URI pro nasazení ze stránky Models v portálu Foundry. Použijte tento koncový bod pro Uri parametr v této dovednosti.

• Autentizace může být založená na klíči pomocí API klíče z vašeho zdroje Foundry nebo Azure OpenAI. Doporučujeme však přístup založený na rolích pomocí spravované identity vyhledávací služby přiřazené roli.

  • Na Azure OpenAI přiřaďte Cognitive Services OpenAI User spravované identitě.

  • V Foundry přiřaďte uživatele Foundry spravované identitě.

    Important

    Nedávno byly přejmenovány role Foundry RBAC. Foundry User, Foundry Owner, Vlastník účtu Foundry a Foundry Project Manager se dříve jmenoval Azure uživatel AI, Azure vlastník AI, Azure vlastník účtu AI a správce Azure AI Project. Během zavádění přejmenování se stále můžou zobrazovat předchozí názvy na některých místech. ID rolí a základní oprávnění se při přejmenování nezmění.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

Omezení dat

Parametry dovedností

* Přesně jedna z apiKey, authIdentity, nebo systémem přiřazené identity služby musí být použita.

commonModelParameters Výchozí nastavení

Vstupy dovedností

Výstupy schopností

Ukázkové definice

Shrnutí pouze textu

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

Text + popis obrázku

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

Strukturovaný numerický vyhledávač faktů

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

Výstup vzorku (zkrácený)

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

Osvědčené postupy

• Dělejte dlouhé dokumenty pomocí dovednosti Text Split , abyste zůstali v kontextovém okně modelu.
• Pro indexování s vysokým objemem věnujte této dovednosti samostatné nasazení modelu, aby kvóty tokenů pro RAG zátěže v době dotazů zůstaly nedotčeny.
• Pro minimalizaci latence umístěte model a vaši službu Azure AI Vyhledávač do stejné Azure oblasti.
• Použití responseFormat.json_schema s GPT-4o pro spolehlivou strukturovanou extrakci a jednodušší mapování na indexová pole.
• Sledujte využití tokenů a odesílejte požadavky na zvýšení kvóty , pokud indexer přetíží vaše limity Tokens per Minute (TPM).

Chyby a varování

Aspekty zabezpečení pro ověřování spravovaných identit

Když dovednost GenAI Prompt používá ověřování spravované identity, Azure AI Vyhledávač získá přístupový token Microsoft Entra pro cílovou skupinu Foundry Tools (https://cognitiveservices.azure.com) a zahrne ji do požadavků odeslaných do koncového bodu určeného uživatelem uri. Ověřování spravované identity se použije, pokud authIdentity je nastavené, nebo když jsou prázdné apiKey a authIdentity služba používá identitu přiřazenou systémem.

Očekává se, že koncový bod, na který odkazujete, bude vaším vlastním prostředkem uri Azure OpenAI nebo Foundry. Podporované domény jsou:

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

podporují se také koncové body Azure API Management (*.azure-api.netAPIM) a vlastní domény, které tyto prostředky předkládají. Vzhledem k tomu, že vlastní doména nebo název hostitele APIM nelze ověřit pouze z názvu, Azure AI Vyhledávač ověří tyto koncové body kontrolou živého připojení v době konfigurace, a ne podle shody domény. Zodpovídáte za konfiguraci a údržbu vztahu mezi koncovým bodem a prostředkem OpenAI nebo Foundry, který je za ním Azure.

Doporučené postupy zabezpečení

Pokud chcete pomoct se zabezpečením nasazení, postupujte podle těchto postupů:

• Nastavte uri pouze koncové body, které vlastníte a důvěřujete jim. Preferujte domény Foundry Tools uvedené dříve. Pokud používáte APIM nebo koncový bod vlastní domény, před povolením spravované identity ho před povolením spravované identity potvrďte před vlastním prostředkem. Důvěryhodný název hostitele není důkazem o vlastnictví.
• Použijte zásadu nejnižšího oprávnění na spravovanou identitu používanou vyhledávací službou:
  • Na Azure OpenAI přiřaďte pouze uživatele OpenAI služeb Cognitive Services.
  • V Foundry přiřaďte pouze uživatele Foundry. Vyhněte se udělování širších rolí.
• Pomocí hraniční sítě (NSP) a privátních koncových bodů nebo integrace virtuální sítě omezte, ke kterým koncovým bodům může vyhledávací služba přistupovat a ze kterých zdrojů cílový prostředek přijímá požadavky.
• Pokud používáte APIM nebo koncový bod vlastní domény, ujistěte se, že brána ověřuje příchozí požadavky a předává je jenom zamýšlenému back-endu. Zásady přístupu byste také měli pravidelně kontrolovat.
• Preferovat spravovanou identitu před apiKey. Pokud používáte apiKey, bezpečně ho uložte a otočte a nevkládejte ho do správy zdrojového kódu. Služba odmítne konfigurace, které nastavují obojí apiKey i authIdentity.
• Pravidelně kontrolujte definice sady dovedností, přiřazení rolí spravované identity a konfigurace APIM a vlastních domén a ověřte, že uri hodnoty, řízení přístupu a oprávnění identit zůstávají aktuální a vhodné. Zkontrolujte změny konfigurace prostřednictvím zavedených procesů správy změn a kontroly zabezpečení.
• Monitorujte protokoly přihlášení Azure OpenAI, Foundry Tools a Foundry, události ověřování a přístupové protokoly pro neočekávané nebo neautorizované aktivity.
• Odeberte nepoužívané dovednosti, koncové body, přiřazení rolí a klíče rozhraní API, které už nejsou potřeba.

Omezení přístupu ke konfiguraci sady dovedností

Uživatelé, kteří můžou vytvářet, upravovat nebo spouštět sady dovedností, řídí cílový koncový bod (uri) i konfiguraci ověřování používanou dovedností. Vzhledem k tomu, že dovednost odesílá token spravované identity pro cílovou skupinu Foundry Tools do tohoto koncového bodu, omezte tato oprávnění na důvěryhodné správce a při konfiguraci dovedností s podporou spravované identity postupujte podle standardních procesů správy změn a kontroly zabezpečení.

Viz také

• Azure AI Vyhledávač vestavěné indexery
• Integrovaná vektorizace
• Jak definovat dovednosti
• Jak generovat dokončení chatu pomocí Azure AI modelové inference (Foundry)
• Strukturované výstupy v Azure OpenAI