Навык GenAI Prompt

Навык GenAI (Generative AI) Prompt выполняет запрос chat completion против большой языковой модели (LLM), развернутой в Azure OpenAI in Foundry Models или Microsoft Foundry. Используйте этот навык для создания новой информации, которую можно индексировать и хранить в виде поискового контента.

Вот несколько примеров того, как навык подсказок GenAI может помочь вам создавать контент:

• Словесная визуализация изображений
• Подытожить большие текстовые отрывки
• Упростить сложное содержание
• Выполните любую другую задачу, которую можете сформулировать в задании

Навык GenAI Prompt обычно доступен в 2026-04-01 Search Service REST API а также в Azure SDKs, ориентированных на эту версию. Этот навык поддерживает текст, изображения и мультимодальный контент, например, изображения с визуальными элементами и текст, извлеченные из PDF-файлов.

Поддерживаемые модели

• Вы можете использовать любую модель вывода чата , развернутую в Foundry, например модели GPT, DeepSeek-R#, Llama-4-Maverick и Cohere-command-r. Для моделей GPT поддерживаются только конечные точки API завершения чата. Конечные точки, использующие API Azure OpenAI Responses (содержащий /openai/responses в URI), в настоящее время несовместимы.

• Для вербализации изображения модель, используемая для анализа изображения, определяет, какие форматы поддерживаются.

• Для моделей GPT-5 параметр temperature не поддерживается так же, как в предыдущих моделях. Если он определен, его нужно установить в 1.0, так как другие значения приводят к ошибкам.

• Биллинг основан на ценообразовании используемой вами модели.

Необходимые условия

• Ресурс OpenAI Azure OpenAI в ресурсе Foundry Models или Foundry project.

• Поддерживаемая модель, развернутая в вашем ресурсе или проекте.

  • Для Azure OpenAI скопируйте конечную точку с доменом openai.azure.com со страницы Keys and Endpoint в портале Azure. Используйте эту конечную точку для Uri параметра в этом навыке.

  • Для Foundry скопируйте целевой URI для развертывания со страницы Models в портале Foundry. Используйте эту конечную точку для Uri параметра в этом навыке.

• Аутентификация может быть основана на ключах с помощью API-ключа из вашего ресурса Foundry или Azure OpenAI. Однако мы рекомендуем доступ на основе ролей с использованием управляемой идентификации поисковой службы , присваиваемой роли.

  • На Azure OpenAI назначите управляемую идентичность Cognitive Services OpenAI User.

  • В Foundry назначьте пользователя Foundry управляемому удостоверению.

    Important

    Недавно переименованы роли RBAC Foundry. Foundry User, Foundry Owner, Владелец учетной записиFoundry и Foundry Project Manager ранее были названы Azure пользователем ИИ, Azure владельцем ИИ, Azure владельцем учетной записи ИИ и Azure диспетчером Project ИИ. При развертывании переименования могут отображаться предыдущие имена в некоторых местах. Идентификаторы ролей и основные разрешения не изменяются при переименовании.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

Ограничения данных

Параметры навыков

* Должен использоваться ровно один из apiKey, authIdentityили системно назначенная идентичность сервиса.

commonModelParameters По умолчанию

Входные параметры навыков

Выходные данные навыка

Примеры определений

Сводка только для текста

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

Текст + описание изображения

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

Структурированный численный детектор фактов

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

Выход выборки (усечённый)

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

Лучшие практики

• Разделяйте длинные документы на части с помощью навыка Text Split , чтобы оставаться в контекстном окне модели.
• Для индексирования с большим объёмом выделяйте отдельную модель для этого навыка, чтобы квоты на токены для RAG-нагрузок во время запроса оставались неизменными.
• Чтобы минимизировать задержку, разместите модель и ваш сервис Поиск с использованием ИИ Azure в одном регионе Azure.
• Используйте responseFormat.json_schemaGPT-4o для надёжной структурированной экстракции и более простого сопоставления с индексными полями.
• Отслеживайте использование токенов и отправляйте запросы на увеличение квоты , если индексатор насыщает ваши лимиты Tokens per Minute (TPM).

Ошибки и предупреждения

Вопросы безопасности для проверки подлинности управляемых удостоверений

Если навык запроса GenAI использует проверку подлинности управляемого удостоверения, Поиск с использованием ИИ Azure получает маркер доступа Microsoft Entra для аудитории Средств Foundry (https://cognitiveservices.azure.com) и включает его в запросы, отправленные в конечную точку, указанную в параметре uri. Проверка подлинности управляемого удостоверения применяется, если authIdentity задано или когда apiKeyauthIdentity они пусты, а служба использует назначаемое системой удостоверение.

Ожидается, что конечная точка, на которую uri ссылается ваш собственный Azure ресурс OpenAI или Foundry. Поддерживаемые домены:

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

также поддерживаются конечные точки Azure API Management (*.azure-api.net и пользовательские домены, которые находятся перед этими ресурсами. Так как личный домен или имя узла APIM не может быть проверено только с его именем, Поиск с использованием ИИ Azure проверяет эти конечные точки с проверкой динамического подключения во время настройки, а не по сопоставлению домена. Вы несете ответственность за настройку и поддержание связи между конечной точкой и ресурсом OpenAI или Foundry Azure.

Recommended security practices (Рекомендации по безопасности)

Чтобы обеспечить безопасное развертывание, выполните следующие действия.

• Задайте uri только конечные точки, которыми вы владеете и доверяете. Предпочитайте домены средств Foundry, перечисленные ранее. Если вы используете конечную точку APIM или личного домена, убедитесь, что он выполняет интерфейс собственного ресурса перед включением управляемого удостоверения. Доверенное имя узла не является подтверждением владения.
• Примените принцип наименьших привилегий к управляемому удостоверению, используемому службой поиска:
  • В Azure OpenAI назначьте только пользователя OpenAI Cognitive Services.
  • В Foundry назначьте только пользователя Foundry. Избегайте предоставления более широких ролей.
• Используйте периметр безопасности сети (NSP) и частные конечные точки или интеграцию виртуальной сети, чтобы ограничить доступ к конечным точкам службы поиска и источникам, из которых целевой ресурс принимает запросы.
• Если вы используете конечную точку APIM или личного домена, убедитесь, что шлюз проверяет входящие запросы и перенаправляет их только в предназначенную серверную часть. Также следует периодически просматривать свои политики доступа.
• Предпочитайте управляемое удостоверение apiKey. Если вы используете apiKey, сохраните и вращайте его безопасно и не внедряйте его в систему управления версиями. Служба отклоняет конфигурации, которые задают оба apiKey и authIdentity.
• Периодически просматривают определения набора навыков, назначения ролей управляемого удостоверения, а также конфигурации APIM и пользовательского домена, чтобы убедиться, что uri значения, элементы управления доступом и разрешения удостоверений остаются текущими и соответствующими. Просмотрите изменения конфигурации с помощью установленных процессов управления изменениями и проверки безопасности.
• Отслеживайте Azure журналы входа OpenAI, Foundry Tools и Foundry, события проверки подлинности и журналы доступа для непредвиденных или несанкционированных действий.
• Удалите неиспользуемые навыки, конечные точки, назначения ролей и ключи API, которые больше не требуются.

Ограничение доступа к конфигурации набора навыков

Пользователи, которые могут создавать, изменять или запускать наборы навыков, управляют конечной конечной точкой (uri) и конфигурацией проверки подлинности, используемой навыком. Так как навык отправляет маркер управляемого удостоверения для аудитории Foundry Tools в ту конечную точку, ограничьте эти разрешения доверенным администраторам и следуйте стандартным процессам управления изменениями и проверки безопасности при настройке навыков с поддержкой управляемого удостоверения.

См. также

• Поиск с использованием ИИ Azure встроенные индексеры
• Встроенная векторизация
• Как определить набор навыков
• Как генерировать завершения чата с помощью Azure AI model inference (Foundry)
• структурированные выходы в Azure OpenAI