Umiejętność GenAI Prompt

Note

Usługa Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie indeksowanie i interfejsy API zapytań wraz ze źródłem wiedzy wyższego poziomu i interfejsami API bazy wiedzy na potrzeby pobierania zarządzanego. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.

Aby uzyskać terminy dotyczące obsługiwanych połączeń bezpośrednich lub API Management z modelami innych niż Microsoft, zobacz Modele innych firm.

Umiejętność GenAI (Generative AI) Prompt wykonuje żądanie chat completion na dużym modelu językowym (LLM) wdrożonym w Azure OpenAI w Foundry Models lub Microsoft Foundry. Wykorzystaj tę umiejętność do tworzenia nowych informacji, które można indeksować i przechowywać jako treści przeszukiwalne.

Oto kilka przykładów, jak umiejętność generowania promptów GenAI może pomóc Ci tworzyć treści:

  • Ustalizuj obrazy
  • Podsumowanie obszernych fragmentów tekstu
  • Uproszczenie złożonych treści
  • Wykonaj dowolne inne zadanie, które możesz wyrazić w promptie

Użyj interfejsu API REST usługi wyszukiwania 2026-10-01 , aby uzyskać ogólnie dostępne funkcje umiejętności wiersza polecenia genAI. Umiejętności są również dostępne w Azure SDKs, które go obsługują. Ta umiejętność obsługuje tekst, obrazy oraz treści multimodalne, takie jak obrazy z wizualizacjami i tekstem wyodrębnianym z plików PDF.

Wskazówka

Często łączy się tę umiejętność z umiejętnością dzielenia danych. Tutorial multimodalny demonstruje werbalizację obrazów za pomocą dwóch różnych strategii dzielenia danych.

Obsługiwane modele

  • Użyj modelu wnioskowania zakończenia czatu wdrożonego w usłudze Microsoft Foundry, który akceptuje dane wejściowe i parametry generowania umiejętności. Skonfiguruj operację Kończenia czatu, która obsługuje parametry i format odpowiedzi używany przez umiejętności.

  • Do werbalizacji obrazów model, którego używasz do analizy obrazu, decyduje, jakie formaty obrazów są obsługiwane.

  • W modelach GPT-5 parametr ten temperature nie jest obsługiwany w taki sam sposób jak w poprzednich modelach. Jeśli jest zdefiniowany, musi być ustawiony na 1.0, ponieważ inne wartości powodują błędy.

  • Rozliczenia opierają się na cenie modelu, którego używasz.

Note

Wywołania modelu używają publicznego punktu końcowego, chyba że skonfigurujesz kwalifikowaną trasę wykonywania prywatnego. Zobacz Kwalifikacje łączności usługi API Management. Sprawdź regiony IQ (Wyszukiwanie AI platformy Azure) rozwiązania Foundry i regiony modelu openAI Azure podczas wybierania lokalizacji wdrożenia.

Wymagania wstępne

  • Zasób Azure OpenAI w modelach foundry lub Foundry.

  • Wspierany model wdrożony na Twoim zasobu lub projekcie.

    • W przypadku Azure interfejsu OpenAI użyj punktu końcowego zasobu z openai.azure.com domeną jako podstawy dla pełnego identyfikatora URI wywołania rozmów: https://<resource-name>.openai.azure.com/openai/deployments/<deployment-name>/chat/completions?api-version=<downstream-api-version>. Zastąp nazwę wdrożenia i wersję podrzędnego interfejsu API wartościami obsługiwanymi przez wdrożenie Azure OpenAI. Ustaw uri ten pełny adres URL, a nie podstawowy punkt końcowy zasobu. Wersja interfejsu API podrzędnego jest oddzielona od wersji interfejsu API wyszukiwania.

    • W przypadku rozwiązania Foundry użyj identyfikatora URI docelowego ukończenia czatu wdrożenia, w tym ścieżki operacji i wszystkich wymaganych parametrów zapytania dla elementu uri.

  • Uwierzytelnianie może być oparte na kluczach za pomocą klucza API z Twojego zasobu Foundry lub Azure OpenAI. Zalecamy jednak dostęp oparty na rolach przy użyciu tożsamości zarządzanej usługi IQ usługi Foundry przypisanej do roli.

    • W przypadku Azure wdrożeń openAI przypisz użytkownika openAI usług Cognitive Services do przypisanej przez system lub wybranej tożsamości zarządzanej przypisanej przez użytkownika usługi Foundry IQ. Użyj zasobu Azure OpenAI lub nadrzędnego rozwiązania Foundry/Azure AI Services, który hostuje wdrożenie i jest właścicielem skonfigurowanego punktu końcowego jako zakresu, a nie obiektu projektu ani usługi IQ usługi Foundry.

    • W przypadku innych obsługiwanych punktów końcowych modelu hostowanego w usłudze Foundry przypisz użytkownika usługi Foundry do tożsamości zarządzanej w zakresie zasobów wymaganym przez to połączenie modelu.

      Ważna

      Ostatnio zmieniono nazwy ról RBAC usługi Foundry. Użytkownik Foundry, właściciel Foundry, właściciel konta Foundry i menedżer projektu Foundry były wcześniej nazywane odpowiednio użytkownikiem Azure AI, właścicielem Azure AI, właścicielem konta Azure AI i menedżerem projektu Azure AI. Poprzednie nazwy mogą być nadal widoczne w niektórych miejscach, podczas gdy zmiana nazwy jest wdrażana. Identyfikatory ról i uprawnienia podstawowe są niezmienione przez zmianę nazwy.

    • Jeśli usługa API Management zakończy uwierzytelnianie usługi Search i użyje własnej tożsamości zaplecza, autoryzuj wyszukiwanie w bramie. Przypisz rolę modelu do tej tożsamości bramy w zasobie hostingu modelu. Zobacz Zakres roli i identyfikatory tożsamości.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

Limity danych

Limit Notatki
maxTokens Domyślny to 1024 , jeśli zostanie pominięty. Maksymalna wartość zależy od modelu.
Limit czasu żądania Naprawiona na 30 sekund. Weź pod uwagę ten limit, wybierając model do indeksowania zbiorowego, ponieważ modele rozumowania (takie jak o1 i o3) mogą go przekraczać.
Obrazy Obsługiwane są obrazy i adresy URL zakodowane w bazie 64. Limit rozmiaru zależy od modelu.

Parametry umiejętności

Majątek Typ Obowiązkowy Notatki
uri ciąg Tak Ukończ adres URL wywołania modelu, w tym ścieżkę operacji i wszystkie wymagane parametry zapytania. Obsługiwane domeny zasobów to openai.azure.com, , cognitiveservices.azure.comservices.ai.azure.comi models.ai.azure.com. Obsługiwane są również domyślne i niestandardowe domeny bramy usługi API Management. Sam podstawowy adres URL bramy nie jest kompletnym adresem URL operacji. Aby uzyskać informacje o kwalifikacjach protokołu, uwierzytelniania i łączności prywatnej, zobacz Używanie usługi API Management z wywołaniami modelu IQ rozwiązania Foundry. Aby uzyskać informacje o indeksatorach SharePoint z włączonymi uprawnieniami, zobacz Ograniczenia z uprawnieniami SharePoint.
apiKey ciąg Cond.* Tajny klucz do modelu. Zostaw puste pole przy używaniu zarządzanej tożsamości.
authIdentity obiekt Cond.* SearchIndexerDataIdentity Obiekt wybierający dołączoną tożsamość zarządzaną przypisaną przez użytkownika, a nie ciąg identyfikatora klienta. Użyj @odata.type: "#Microsoft.Azure.Search.DataUserAssignedIdentity" identyfikatora zasobu i tożsamości w pliku userAssignedIdentity. Pomiń tę właściwość i apiKey użyj tożsamości przypisanej przez system. Zobacz Tożsamości zarządzane.
commonModelParameters obiekt No Standardowe sterowanie generacją, takie jak temperature, maxTokens, itd.
extraParameters obiekt No Słownik otwarty przekazywany do bazowego API modelu.
extraParametersBehavior ciąg No "pass-through" | "drop" | "error" (wartość domyślna "error").
responseFormat obiekt No Kontroluje, czy model zwraca tekst, wolny obiekt JSON, czy silnie typowany schemat JSON. responseFormat przykłady ładunku: {responseFormat: { type: text }}, {responseFormat: { type: json_object }}, {responseFormat: { type: json_schema }}

* Należy użyć dokładnie jednej zapiKeytożsamości , authIdentitylub przypisanej przez system tożsamości usługi.

W przypadku uwierzytelniania za pomocą klucza ustaw wartość apiKey. W przypadku tożsamości zarządzanej pomiń apiKey i użyj tożsamości przypisanej przez system lub obiektu opisanego authIdentity powyżej.

commonModelParameters wartości domyślne

Parametr Wartość domyślna
model (ustawienie domyślne wdrożenia)
frequencyPenalty 0
presencePenalty 0
maxTokens 1024
temperature 0.7
seed null
stop null

Dane wejściowe dla umiejętności

Nazwa danych wejściowych Typ Obowiązkowy Description
systemMessage ciąg Tak Instrukcje na poziomie systemu (np. "Jesteś pomocnym asystentem.").
userMessage ciąg Tak Monit użytkownika.
text ciąg No Opcjonalny tekst dołączany do userMessage (scenariusze wyłącznie tekstowe).
image string (podstawowy adres URL danych 64) No Dodaje obraz do promptu (tylko modele multimodalne).
imageDetail struna (low | high | auto) No Wskazówka wierności dla modeli wielomodalnych Azure OpenAI.

Dane wyjściowe umiejętności

Nazwa danych wyjściowych Typ Description
response łańcuch lub obiekt JSON Wyjście modelu w formacie wymaganym przez responseFormat.type.
usageInformation Obiekt JSON Liczba tokenów i echo parametrów modelu.

Przykładowe definicje

Podsumowywanie tylko tekst

Ten kompletny przykład umiejętności podsumowuje zawartość dokumentu i zawiera opcjonalną instrukcję etykietowania wygenerowanej odpowiedzi. Zastąp punkt końcowy, wdrożenie i klucz obsługiwaną konfiguracją modelu. Wersja interfejsu API openAI Azure adresu URL jest oddzielona od wersji interfejsu API wyszukiwania.

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

Dokumentacja: Zestawy umiejętności — tworzenie lub aktualizowanie.

Opcjonalnie etykieta wygenerowana tekst

Poprzednie przykładowe miejsca Begin the response with "AI-generated content:". w pliku systemMessage. Tę instrukcję można również umieścić w pliku userMessage. Wybierz własne sformułowanie, umieszczanie i język lub pomiń instrukcję, jeśli nie potrzebujesz widocznego ujawnienia.

Poniższa instrukcja modelu może się różnić. Jeśli każda odpowiedź musi zawierać etykietę, dodaj ją lub zweryfikuj ją deterministycznie w aplikacji, zamiast polegać tylko na wierszu polecenia. Usługa Foundry IQ nie wstawia automatycznie tekstu ujawniania informacji.

Ten opcjonalny widoczny tekst nie jest weryfikowalny maszynowo, sprawdzony, znak wodny, poświadczenia zawartości lub implementacja C2PA. Nie definiuje wymagań prawnych ani wymagań dotyczących zgodności. Takie samo podejście monitujące dotyczy obsługiwanych konfiguracji modelu bezpośredniego, usługi API Management i modelu połączonego z administratorem; nie zmienia ich modelu, uwierzytelniania, sieci ani ograniczeń wzbogacania chronionych uprawnieniami.

Tekst + opis obrazu

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

Ustrukturyzowany numeryczny wyszukiwacz faktów

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

Wyjście próbki (obcięte)

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

Najlepsze rozwiązania

  • Rozciągaj długie dokumenty za pomocą umiejętności Text Split , aby pozostać w oknie kontekstowym modelu.
  • Dla indeksowania o dużym wolumenie należy zaznaczyć osobne wdrożenie modelu do tej umiejętności, aby kwoty tokenów dla obciążeń RAG w czasie zapytań pozostały niezmienione.
  • Aby zminimalizować opóźnienia, znajdź model i usługę IQ rozwiązania Foundry w tym samym regionie Azure.
  • Użycie responseFormat.json_schema z GPT-4o dla niezawodnej strukturalnej ekstrakcji i łatwiejszego mapowania na pola indeksowe.
  • Monitoruj wykorzystanie tokenów i składaj wnioski o zwiększenie limitu , jeśli indekser przekroczy limity Tokens per Minute (TPM).

Błędy i ostrzeżenia

Warunek Wynik
Brakujące lub nieważne uri Error
Nie określono metody uwierzytelniania Error
Zarówno jak apiKey i dostarczone authIdentity Error
Nieobsługiwany model dla promptu multimodalnego Error
Dane wejściowe przekraczają limit tokenów modelu Error
Model zwraca nieprawidłowy JSON dla json_schema Ostrzeżenie: Nieprzetworzony ciąg zwrócony w response

Ograniczenia z uprawnieniami SharePoint

Gdy indeksator pozyska SharePoint list ACL, ta umiejętność obsługuje punkty końcowe Azure OpenAI i Microsoft Foundry w następujących domenach: openai.azure.com, cognitiveservices.azure.com, services.ai.azure.comi models.ai.azure.com.

Trasy usługi APIM, domena niestandardowa i trasy innych firm nie są obsługiwane dla tej konfiguracji, niezależnie od ustawień uwierzytelniania lub sieci. Użyj obsługiwanego punktu końcowego lub pomiń opcjonalny wzbogacanie modelu podczas przechowywania pozyskiwania listy ACL.

Ta umiejętność nie jest obsługiwana w przypadku pozyskiwania etykiet poufności, w tym łączenia etykiet poufności z listami ACL.

Zagadnienia dotyczące zabezpieczeń uwierzytelniania tożsamości zarządzanej

Gdy umiejętność GenAI Prompt korzysta z uwierzytelniania tożsamości zarządzanej, funkcja IQ usługi Foundry uzyskuje token dostępu Microsoft Entra dla odbiorców narzędzi Foundry Tools (https://cognitiveservices.azure.com) i uwzględnia go w żądaniach wysyłanych do punktu końcowego określonego przez uri. Uwierzytelnianie tożsamości zarządzanej ma zastosowanie w przypadku authIdentity ustawienia lub gdy zarówno, apiKey jak i authIdentity są puste, a usługa korzysta z tożsamości przypisanej przez system.

Punkt końcowy, do których odwołuje uri się użytkownik, powinien być twoim własnym zasobem Azure OpenAI lub Foundry. Aby uzyskać informacje o obsługiwanych domenach punktów końcowych, zobacz Parametry umiejętności.

Azure API Management (APIM) punktów końcowych (*.azure-api.net) i domen niestandardowych, które frontują te zasoby, są również obsługiwane. Ponieważ domena niestandardowa lub nazwa hosta usługi APIM nie może być zweryfikowana z samej nazwy, funkcja IQ usługi Foundry weryfikuje te punkty końcowe przy użyciu kontroli łączności na żywo w czasie konfiguracji, a nie przez dopasowanie domeny. Odpowiadasz za konfigurowanie i utrzymywanie relacji między punktem końcowym a zasobem Azure OpenAI lub Foundry.

Aby uzyskać informacje o indeksatorach SharePoint z włączonymi uprawnieniami, zobacz Ograniczenia z uprawnieniami SharePoint.

Note

Token tożsamości zarządzanej wystawiony dla odbiorców narzędzi Foundry Tools jest prawidłowy dla wszystkich narzędzi Foundry Tools lub Azure zasób OpenAI, na którym jest autoryzowana tożsamość. Wysłanie go do niezaufanego punktu końcowego może uwidocznić token.

Aby ułatwić utrzymanie bezpiecznego wdrożenia, postępuj zgodnie z następującymi rozwiązaniami:

  • Ustaw uri tylko punkty końcowe, których jesteś właścicielem i ufasz. Preferuj domeny narzędzi foundry wymienione wcześniej. Jeśli używasz usługi APIM lub punktu końcowego domeny niestandardowej, przed włączeniem tożsamości zarządzanej upewnij się, że jest on frontem własnego zasobu. Zaufana nazwa hosta nie jest dowodem własności.
  • Zastosuj zasadę najniższych uprawnień do tożsamości zarządzanej używanej przez usługę IQ usługi Foundry:
    • W Azure interfejsie OpenAI przypisz tylko użytkownika openAI usług Cognitive Services.
    • W witrynie Foundry przypisz tylko użytkownika usługi Foundry. Unikaj udzielania szerszych ról.
  • Użyj obwodu zabezpieczeń sieci (NSP) i prywatnych punktów końcowych lub integracji z siecią wirtualną, aby ograniczyć punkty końcowe, z których może uzyskiwać dostęp usługa IQ rozwiązania Foundry, oraz źródła, z których korzysta zasób docelowy.
  • Jeśli używasz usługi APIM lub punktu końcowego domeny niestandardowej, upewnij się, że brama weryfikuje żądania przychodzące i przekazuje je tylko do zamierzonego zaplecza. Należy również okresowo przeglądać zasady dostępu.
  • Preferuj tożsamość zarządzaną za pośrednictwem apiKey. Jeśli używasz apiKeymetody , zapisz ją i obracaj ją bezpiecznie i nie osadzaj jej w kontroli źródła. Usługa odrzuca konfiguracje, które ustawiają zarówno , jak apiKey i authIdentity.
  • Okresowo przejrzyj definicje zestawu umiejętności, przypisania ról tożsamości zarządzanej oraz konfiguracje usługi APIM i domeny niestandardowej, aby potwierdzić, że uri wartości, mechanizmy kontroli dostępu i uprawnienia tożsamości pozostają aktualne i odpowiednie. Przejrzyj zmiany konfiguracji za pomocą ustanowionych procesów zarządzania zmianami i przeglądu zabezpieczeń.
  • Monitoruj dzienniki logowania Azure OpenAI, Foundry Tools i Foundry, zdarzenia uwierzytelniania i dzienniki dostępu pod kątem nieoczekiwanych lub nieautoryzowanych działań.
  • Usuń nieużywane umiejętności, punkty końcowe, przypisania ról i klucze interfejsu API, które nie są już wymagane.

Ograniczanie dostępu do konfiguracji zestawu umiejętności

Użytkownicy, którzy mogą tworzyć, modyfikować lub uruchamiać zestawy umiejętności, kontrolują zarówno docelowy punkt końcowy (uri), jak i konfigurację uwierzytelniania używaną przez umiejętności. Ponieważ umiejętność wysyła token tożsamości zarządzanej dla odbiorców narzędzi Foundry Tools do tego punktu końcowego, ogranicz te uprawnienia do zaufanych administratorów i postępuj zgodnie ze standardowymi procesami zarządzania zmianami i przeglądu zabezpieczeń podczas konfigurowania umiejętności z obsługą tożsamości zarządzanej.

Zobacz także