GenAI-Prompt-Fähigkeit

Hinweis

Foundry IQ (Azure KI-Suche) bietet direkte Indizierungs- und Abfrage-APIs zusammen mit Wissensquellen- und Knowledge Base-APIs auf höherer Ebene für den verwalteten Abruf. Verwenden Sie das Azure Portal, REST-APIs oder Azure SDKs, um diese Funktionen zu konfigurieren, oder verbinden Sie Agents mit Wissensdatenbanken im Microsoft Foundry-Portal.

Bedingungen, die für unterstützte direkte oder API-Verwaltungsverbindungen mit Nicht-Microsoft Modellen gelten, finden Sie unter Drittanbietermodelle.

Die GenAI (Generative AI) Prompt-Fähigkeit führt eine Chatabschlussanforderung für ein großes Sprachmodell (LLM) aus, das in Azure OpenAI in Foundry Models oder Microsoft Foundry bereitgestellt wird. Verwenden Sie diese Fertigkeit, um neue Informationen zu erstellen, die als durchsuchbare Inhalte indiziert und gespeichert werden können.

Im Folgenden finden Sie einige Beispiele dafür, wie die GenAI-Promt-Fertigkeit Ihnen beim Erstellen von Inhalten helfen kann:

  • Verbalisieren von Bildern
  • Zusammenfassen großer Textabschnitte
  • Vereinfachen komplexer Inhalte
  • Führen Sie alle anderen Aufgaben aus, die Sie in einem Prompt formulieren können

Verwenden Sie die REST-API des Suchdiensts 2026-10-01 für allgemein verfügbare GenAI Prompt-Fähigkeiten. Die Fähigkeit steht auch in Azure SDKs zur Verfügung, die sie unterstützen. Diese Fähigkeit unterstützt Text, Bild und multimodale Inhalte, z. B. Bilder mit visuellen Elementen und Aus PDF-Dateien extrahierten Text.

Tip

Es ist üblich, diese Fähigkeit mit einer Datenabschnittskompetenz zu kombinieren. Das Multimodale Lernprogramm veranschaulicht die Bildverbalisierung mit zwei verschiedenen Datenabschnittsstrategien.

Unterstützte Modelle

  • Verwenden Sie ein in Microsoft Foundry bereitgestelltes Ableitungsmodell für Chatabschluss, das die Eingaben und Generierungsparameter der Fähigkeiten akzeptiert. Konfigurieren Sie einen Chat-Abschlussvorgang, der die parameter und das Antwortformat unterstützt, das von Ihrer Fähigkeit verwendet wird.

  • Bei der Bildverbalisierung bestimmt das Modell, das Sie zum Analysieren des Bilds verwenden, welche Bildformate unterstützt werden.

  • Bei GPT-5-Modellen wird der temperature-Parameter nicht auf die gleiche Weise wie vorherige Modelle unterstützt. Wenn definiert, muss es auf 1.0 festgelegt werden, da andere Werte zu Fehlern führen.

  • Die Abrechnung basiert auf den Preisen des verwendeten Modells.

Hinweis

Modellaufrufe verwenden einen öffentlichen Endpunkt, es sei denn, Sie konfigurieren eine berechtigte private Ausführungsroute. Siehe API-Verwaltungskonnektivitätsqualifikationen. Überprüfen Sie die Regionen foundry IQ (Azure KI-Suche) und die Azure OpenAI-Modellregionen bei der Auswahl von Bereitstellungsstandorten.

Voraussetzungen

  • Eine Azure OpenAI in Foundry Models-Ressource oder ein Foundry-Projekt.

  • Ein unterstütztes Modell, das für Ihre Ressource oder Ihr Projekt bereitgestellt wird.

    • Verwenden Sie für Azure OpenAI den Ressourcenendpunkt mit der openai.azure.com Domäne als Basis für einen vollständigen Chatabschluss-Aufruf-URI: https://<resource-name>.openai.azure.com/openai/deployments/<deployment-name>/chat/completions?api-version=<downstream-api-version>. Ersetzen Sie den Bereitstellungsnamen und die downstreame API-Version durch Werte, die von Ihrer Azure OpenAI-Bereitstellung unterstützt werden. Legen Sie uri diese vollständige URL und nicht den Ressourcenbasisendpunkt fest. Die nachgeschaltete API-Version ist von der Such-API-Version getrennt.

    • Verwenden Sie für Foundry den vollständigen Chatabschlussziel-URI der Bereitstellung, einschließlich des Vorgangspfads und aller erforderlichen Abfrageparameter, für uri.

  • Die Authentifizierung kann mit einem API-Schlüssel aus Ihrer Foundry- oder Azure OpenAI-Ressource schlüsselbasiert sein. Wir empfehlen jedoch den rollenbasierten Zugriff mithilfe einer verwalteten Identität des Foundry IQ-Diensts , die einer Rolle zugewiesen ist.

    • Weisen Sie für Azure OpenAI-Bereitstellungen cognitive Services OpenAI User dem vom Foundry IQ-Dienst zugewiesenen oder ausgewählten vom Benutzer zugewiesenen verwalteten Identität zu. Verwenden Sie die Azure OpenAI- oder übergeordnete Foundry/Azure AI Services-Ressource, die die Bereitstellung hostet und den konfigurierten Endpunkt als Bereich, nicht als Projektobjekt oder Foundry IQ-Dienst besitzt.

    • Weisen Sie für andere unterstützte, vom Foundry gehostete Modellendpunkte die verwaltete Identität dem verwalteten Identitätsbereich zu, der von dieser Modellverbindung benötigt wird.

      Important

      Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

    • Wenn die API-Verwaltung die Suchauthentifizierung beendet und eine eigene Back-End-Identität verwendet, autorisieren Sie die Suche am Gateway. Weisen Sie der Gatewayidentität stattdessen die Modellrolle für die Modellhostingressource zu. Siehe Rollenbereichs- und Identitätsbezeichner.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

Datenlimits

Limit Hinweise
maxTokens Der Standardwert ist 1024, wenn nicht angegeben. Der Maximalwert ist modellabhängig.
Anforderungstimeout Wurde mit 30 Sekunden behoben. Berücksichtigen Sie diesen Grenzwert, wenn Sie ein Modell für die Massenindizierung auswählen, da die Gründe für Modelle (z. B. o1 und o3) dies möglicherweise überschreiten.
Images Base64-codierte Bilder und Bild-URLs werden unterstützt. Größenbeschränkung ist modellabhängig.

Qualifikationsparameter

Eigentum Typ Erforderlich Hinweise
uri string Yes Vollständige Modellaufruf-URL, einschließlich des Vorgangspfads und aller erforderlichen Abfrageparameter. Unterstützte Ressourcendomänen sind openai.azure.com, services.ai.azure.com, cognitiveservices.azure.com, und models.ai.azure.com. API-Verwaltungsstandard- und benutzerdefinierte Gatewaydomänen werden ebenfalls unterstützt. Eine Gatewaybasis-URL allein ist keine vollständige Vorgangs-URL. Informationen zu Protokoll-, Authentifizierungs- und privaten Konnektivitätsqualifikationen finden Sie unter Verwenden der API-Verwaltung mit Foundry IQ-Modellaufrufen. Informationen zu berechtigungsfähigen SharePoint Indexern finden Sie unter Einschränkungen mit SharePoint Berechtigungen.
apiKey string Cond.* Geheimer Schlüssel für das Modell. Leer lassen, wenn Sie verwaltete Identität verwenden.
authIdentity Objekt Cond.* Ein SearchIndexerDataIdentity Objekt, das eine angefügte, vom Benutzer zugewiesene verwaltete Identität auswählt, nicht eine Client-ID-Zeichenfolge. Verwenden @odata.type: "#Microsoft.Azure.Search.DataUserAssignedIdentity" und die Ressourcen-ID der Identität in userAssignedIdentity. Lassen Sie diese Eigenschaft aus und apiKey verwenden Sie die vom System zugewiesene Identität. Siehe Verwaltete Identitäten.
commonModelParameters Objekt No Steuerelemente der Standardgenerierung, wie temperature. maxTokens usw.
extraParameters Objekt No Geöffnetes Wörterbuch, das an die zugrunde liegende Modell-API übergeben wird.
extraParametersBehavior string No "pass-through" | "drop" | "error" (Standardeinstellung "error").
responseFormat Objekt No Steuert, ob das Modell Text, ein Freiform-JSON-Objekt oder ein stark typiertes JSON-Schema zurückgibt. responseFormat Nutzlastbeispiele: {responseFormat: { type: text }}, {responseFormat: { type: json_object }}, {responseFormat: { type: json_schema }}

* Genau eine der apiKeyvom authIdentitySystem zugewiesenen Identitäten des Diensts muss verwendet werden.

Legen Sie für die Schlüsselauthentifizierung fest apiKey. Für verwaltete Identitäten müssen Sie die vom System zugewiesene Identität oder das authIdentity oben beschriebene Objekt weglassen apiKey und verwenden.

commonModelParameters Standardwerte

Parameter Vorgabe
model (Bereitstellungsstandard)
frequencyPenalty 0
presencePenalty 0
maxTokens 1024
temperature 0.7
seed null
stop null

Qualifikationseingaben

Eingabename Typ Erforderlich Description
systemMessage string Yes Anweisung auf Systemebene (z. B. "Sie sind ein hilfreicher Assistent.").
userMessage string Yes Bentzerprompt
text string No Optionaler Text, der an userMessage angefügt ist (nur Textszenarien).
image String (Base 64 Data-URL) No Fügt der Prompt-Aufforderung ein Bild hinzu (nur multimodale Modelle).
imageDetail String (low | high | auto) No Fidelity-Hinweis für multimodale Azure OpenAI-Modelle.

Skill-Ergebnisse

Ausgabename Typ Description
response String oder JSON-Objekt Modellausgabe im von responseFormat.type geforderten Format.
usageInformation JSON-Objekt Tokenanzahl und Echo von Modellparametern.

Beispieldefinitionen

Nur Textzusammenfassung

In diesem vollständigen Qualifikationsbeispiel werden Dokumentinhalte zusammengefasst und eine optionale Anweisung zum Bezeichnen der generierten Antwort eingeschlossen. Ersetzen Sie den Endpunkt, die Bereitstellung und den Schlüssel durch Ihre unterstützte Modellkonfiguration. Die Azure OpenAI-API-Version der URL ist von der Such-API-Version getrennt.

{
  "@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. Begin the response with \"AI-generated content:\".'"
    },
    { "name": "userMessage", "source": "='Summarize the following text:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview",
  "apiKey": "<api-key>",
  "commonModelParameters": { "temperature": 0.3 }
}

Referenz: Skillsets – Erstellen oder Aktualisieren.

Optional generierten Text beschriften

Im vorangehenden Beispiel wird Begin the response with "AI-generated content:". in systemMessage. Sie können diese Anweisung auch in userMessage. Wählen Sie Ihre eigenen Formulierungen, Platzierung und Sprache aus, oder lassen Sie die Anweisung aus, wenn Sie keine sichtbare Offenlegung benötigen.

Die folgende Modellanweisung kann variieren. Wenn jede Antwort über eine Bezeichnung verfügen muss, fügen Sie sie in Ihrer Anwendung deterministisch hinzu, oder überprüfen Sie sie, anstatt nur auf die Eingabeaufforderung zu vertrauen. Findry IQ fügt nicht automatisch Offenlegungstext ein.

Dieser optionale sichtbare Text ist keine computerprüfbare Provenienz, Wasserzeichen, Inhaltsanmeldeinformationen oder eine C2PA-Implementierung. Es definiert keine gesetzlichen oder Complianceanforderungen. Derselbe Aufforderungsansatz gilt für unterstützte direkte, API-Verwaltungs- und vom Administrator verbundene Modellkonfigurationen; Es ändert nicht das Modell, die Authentifizierung, das Netzwerk oder die Einschränkungen für die berechtigungsgeschützte Anreicherung.

Text- und Bildbeschreibung

{
  "@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": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>"
  },
  "responseFormat": { "type": "text" }
}

Strukturierte numerische Faktensuche

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

Beispielausgabe (gekürzt):

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

Bewährte Methoden

  • Blockieren Sie lange Dokumente mit der Fähigkeit Textteilung, um im Kontextfenster des Modells zu bleiben.
  • Für die hochvolumige Indizierung sollten Sie dieser Fähigkeit eine separate Modellbereitstellung zuweisen, sodass Tokenkontingente für RAG-Workloads von Abfragezeit nicht betroffen sind.
  • Um die Latenz zu minimieren, suchen Sie das Modell und Ihren Foundry IQ-Dienst in derselben Azure Region.
  • Verwendung responseFormat.json_schema mit GPT-4o für zuverlässige strukturierte Extraktion und einfachere Zuordnung zu Indexfeldern.
  • Überwachen Sie die Token-Nutzung und stellen Sie Anforderungen zur Kontingenterhöhung, wenn der Indexer Ihre Token pro Minute (TPM)-Limits erreicht.

Fehler und Warnungen

Zustand Ergebnis
Fehlende oder ungültige uri Fehler
Es wurde keine Authentifizierungsmethode angegeben. Fehler
Sowohl als apiKey, als auch als authIdentity unterstützt Fehler
Nicht unterstütztes Modell für eine multimodale Eingabeaufforderung Fehler
Die Eingabe überschreitet die Modelltokengrenze. Fehler
Das Modell gibt ungültigen JSON-Code für json_schema Warnung: Unformatierte Zeichenfolge, die in response

Einschränkungen mit SharePoint Berechtigungen

Wenn Ihr Indexer SharePoint ACLs einnimmt, unterstützt diese Fähigkeit First-Party-Azure OpenAI- und Microsoft Foundry-Endpunkte in diesen Domänen: openai.azure.com, , , cognitiveservices.azure.comund services.ai.azure.commodels.ai.azure.com.

APIM-, benutzerdefinierte Domänen- und Drittanbieterrouten werden für diese Konfiguration unabhängig von Authentifizierungs- oder Netzwerkeinstellungen nicht unterstützt. Verwenden Sie einen unterstützten Endpunkt, oder lassen Sie die optionale Modellanreicherung aus, während die ACL-Aufnahme beibehalten wird.

Diese Fähigkeit wird bei der Aufnahme von Vertraulichkeitsbezeichnungen nicht unterstützt, auch wenn Sie Vertraulichkeitsbezeichnungen mit ACLs kombinieren.

Sicherheitsüberlegungen für die verwaltete Identitätsauthentifizierung

Wenn die GenAI Prompt-Fähigkeit die verwaltete Identitätsauthentifizierung verwendet, erhält Foundry IQ ein Microsoft Entra Zugriffstoken für die Zielgruppe der Foundry Tools (https://cognitiveservices.azure.com) und schließt es in Anforderungen ein, die an den durch uriden angegebenen Endpunkt gesendet werden. Die verwaltete Identitätsauthentifizierung gilt, wenn authIdentity festgelegt wird oder wenn beide apiKey leer sind und authIdentity der Dienst die vom System zugewiesene Identität verwendet.

Der endpunkt, auf uri den verwiesen wird, wird erwartet, dass es sich um Ihre eigene Azure OpenAI- oder Foundry-Ressource handelt. Unterstützte Endpunktdomänen finden Sie unter Skill-Parameter.

Azure API Management (APIM)-Endpunkte (*.azure-api.net) und benutzerdefinierte Domänen, die diese Ressourcen frontieren, werden ebenfalls unterstützt. Da ein benutzerdefinierter Domänen- oder APIM-Hostname nicht allein anhand seines Namens überprüft werden kann, überprüft Foundry IQ diese Endpunkte mit einer Live-Konnektivitätsprüfung zur Konfigurationszeit und nicht nach dem Domänenabgleich. Sie sind dafür verantwortlich, die Beziehung zwischen dem Endpunkt und der Azure OpenAI- oder Foundry-Ressource dahinter zu konfigurieren und zu verwalten.

Informationen zu berechtigungsfähigen SharePoint Indexern finden Sie unter Einschränkungen mit SharePoint Berechtigungen.

Hinweis

Ein für die Zielgruppe "Foundry Tools" ausgestelltes verwaltetes Identitätstoken ist für alle Foundry Tools oder Azure OpenAI-Ressource gültig, für die die Identität autorisiert ist. Das Senden an einen nicht vertrauenswürdigen Endpunkt könnte das Token verfügbar machen.

Befolgen Sie die folgenden Methoden, um eine sichere Bereitstellung aufrechtzuerhalten:

  • Legen Sie nur auf Endpunkte fest uri , die Sie besitzen und vertrauen. Bevorzugen Sie die zuvor aufgeführten Domänen der Foundry Tools. Wenn Sie einen APIM- oder benutzerdefinierten Domänenendpunkt verwenden, stellen Sie sicher, dass sie Ihre eigene Ressource vorgibt, bevor Sie verwaltete Identität aktivieren. Ein vertrauenswürdig aussehender Hostname ist kein Besitznachweis.
  • Wenden Sie das Prinzip der geringsten Rechte auf die verwaltete Identität an, die vom Foundry IQ-Dienst verwendet wird:
    • Weisen Sie auf Azure OpenAI nur Cognitive Services OpenAI User zu.
    • Weisen Sie bei Foundry nur den Foundry-Benutzer zu. Vermeiden Sie die Gewährung breiterer Rollen.
  • Verwenden Sie den Netzwerksicherheitsperimeter (Network Security Perimeter, NSP) und private Endpunkte oder die VNet-Integration, um einzuschränken, welche Endpunkte der Foundry IQ-Dienst erreichen kann und von welchen Quellen die Zielressource Anforderungen akzeptiert.
  • Wenn Sie einen APIM- oder benutzerdefinierten Domänenendpunkt verwenden, stellen Sie sicher, dass das Gateway eingehende Anforderungen überprüft und nur an das beabsichtigte Back-End weiterleitet. Außerdem sollten Sie die Zugriffsrichtlinien regelmäßig überprüfen.
  • Bevorzugen Sie verwaltete Identität gegenüber apiKey. Wenn Sie es verwenden apiKey, speichern und drehen Sie sie sicher, und betten Sie sie nicht in die Quellcodeverwaltung ein. Der Dienst lehnt Konfigurationen ab, die sowohl als apiKeyauch authIdentity .
  • Überprüfen Sie in regelmäßigen Abständen Skillsetdefinitionen, Zuordnungen verwalteter Identitätsrollen sowie APIM- und benutzerdefinierte Domänenkonfigurationen, um zu bestätigen, dass uri Werte, Zugriffssteuerungen und Identitätsberechtigungen aktuell und angemessen bleiben. Überprüfen Sie Konfigurationsänderungen durch Ihre etablierten Change-Management- und Sicherheitsüberprüfungsprozesse.
  • Überwachen Sie Azure OpenAI-, Foundry-Tools- und Foundry-Anmeldeprotokolle, Authentifizierungsereignisse und Zugriffsprotokolle auf unerwartete oder nicht autorisierte Aktivitäten.
  • Entfernen Sie nicht verwendete Fähigkeiten, Endpunkte, Rollenzuweisungen und API-Schlüssel, die nicht mehr benötigt werden.

Einschränken des Zugriffs auf die Konfiguration von Skillset

Benutzer, die Skillsets erstellen, ändern oder ausführen können, steuern sowohl den Zielendpunkt (uri) als auch die von der Qualifikation verwendete Authentifizierungskonfiguration. Da die Fähigkeit ein verwaltetes Identitätstoken für die Zielgruppe "Foundry Tools" an diesen Endpunkt sendet, beschränken Sie diese Berechtigungen auf vertrauenswürdige Administratoren, und befolgen Sie Ihre standardmäßigen Change-Management- und Sicherheitsüberprüfungsprozesse beim Konfigurieren verwalteter Identitätsfunktionen.

Siehe auch