Создание агента знаний в службе "Поиск ИИ Azure"

2025-06-01

Замечание

Эта функция сейчас доступна в общедоступной предварительной версии. Этот предварительный просмотр предоставляется без соглашения об уровне обслуживания и не предназначается для производственных рабочих нагрузок. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены. Для получения дополнительной информации см. Дополнительные условия использования для предварительных версий Microsoft Azure.

В Azure AI Search агент знаний — это основной ресурс, представляющий подключение к модели завершения чата для использования в рабочих нагрузках с агентским извлечением. Агент знаний применяется методом retrieve в конвейере извлечения информации, основанном на LLM.

Агент знаний определяет:

Модель, которая предоставляет возможности рассуждений
Целевой индекс поиска, используемый во время запроса
Параметры индекса для настройки поведения по умолчанию и формирования ответов

После создания агента знаний его свойства можно обновлять в любое время. Если агент знаний используется, обновления вступают в силу для следующего задания.

Предпосылки

Знакомство с концепциями агентного извлечения и сценариями использования.
Поддерживаемая модель завершения чата в Azure OpenAI.
Поиск ИИ Azure в любом регионе, который предоставляет семантический рангировщик, на базовой ценовой категории или выше. Служба поиска должна иметь управляемое удостоверение для ролевого доступа к модели.
Разрешения для поиска ИИ Azure. Участник службы поиска может создавать агент знаний и управлять ими. Средство чтения данных индекса поиска может выполнять запросы. Инструкции приведены в этой статье.
Индекс поиска, содержащий обычный текст или векторы. Индекс должен соответствовать требованиям для агентического извлечения, включая семантическую конфигурацию с defaultConfiguration указанным.
Требования API. Чтобы создать или использовать агент знаний, воспользуйтесь REST API для управления данными 2025-05-01-preview. Кроме того, используйте предварительно подготовленный пакет пакета Azure SDK, который предоставляет API агента знаний: Пакет SDK azure для Python, пакет SDK Azure для .NET, пакет SDK Azure для Java.

Чтобы выполнить действия, описанные в этом руководстве, рекомендуется использовать Visual Studio Code с клиентом REST для отправки вызовов REST API предварительной версии в службу поиска ИИ Azure. В настоящее время нет поддержки портала.

Развертывание модели для агентного извлечения

Убедитесь, что у вас есть поддерживаемая модель, к которой Azure AI Поиск может получить доступ. В следующей инструкции предполагается, что модель Azure AI Foundry является поставщиком.

Войдите на портал Azure AI Foundry.
Разверните поддерживаемую модель с помощью этих инструкций.
Убедитесь, что управляемая удостоверяющая личность службы поиска имеет разрешения пользователя Cognitive Services на ресурсе Azure OpenAI.

Если вы тестируете локально, вам нужны также разрешения Cognitive Services User.

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

Используйте Azure OpenAI или эквивалентную модель с открытым кодом:

gpt-4o
gpt-4o-mini
gpt-4.1
gpt-4.1-nano
gpt-4.1-mini

Настройка доступа

Службе поиска ИИ Azure требуется доступ к модели завершения чата. Вы можете использовать проверку подлинности на основе ключей или на основе ролей (рекомендуется).

Использование проверки подлинности на основе ролей

Если вы используете проверку подлинности на основе ролей, на ресурсе Azure OpenAI назначьте роль пользователя Cognitive Services управляемому удостоверению службы поиска.

В Azure для назначения ролей необходимо иметь разрешения «Владелец» или «Администратор доступа пользователя» у модельного поставщика.

Настройте поиск ИИ Azure с использованием управляемой идентичности.
В поставщике моделей, например Foundry Model, создайте назначение ролей, которое предоставляет разрешения пользователя Cognitive Services для управляемого удостоверения службы поиска. Если вы тестируете локально, назначьте себе ту же роль.
Для локального тестирования выполните действия, описанные в кратком руководстве: Подключение без ключей, чтобы получить персональный токен доступа и убедиться, что вы вошли в определенную подписку и тенант. Вставьте свой личный идентификатор в переменную @accessToken. Запрос, который подключается с использованием вашей личной идентификации, должен выглядеть следующим образом:
```
@search-url=<YOUR SEARCH SERVICE URL>
@accessToken=<YOUR PERSONAL ID>

# List Indexes
GET https://{{search-url}}/indexes?api-version=2025-05-01-preview
Authorization: Bearer {{accessToken}}
```

Это важно

Если вы используете проверку подлинности на основе ролей, обязательно удалите все ссылки на ключ API в запросах. В запросе, указывающего оба подхода, ключ API используется вместо ролей.

Использование проверки подлинности на основе ключей

Ключи API можно использовать, если у вас нет разрешения на создание назначений ролей.

Скопируйте ключ API администратора поиска Azure и вставьте его в качестве переменной api-key в HTTP-файл или REST: @api-key

Укажите ключ API для каждого запроса. Запрос, который подключается с помощью ключа API, должен выглядеть следующим образом:

 @search-url=<YOUR SEARCH SERVICE URL>
 @search-api-key=<YOUR SEARCH SERVICE ADMIN API KEY>

# List Indexes
GET https://{{search-url}}/indexes?api-version=2025-05-01-preview
   Content-Type: application/json
   @api-key: {{search-api-ke}}

Проверка существующих информационных агентов

В следующем запросе перечислены агенты знаний по имени. В коллекции агентов знаний все агенты должны иметь уникальные имена. Полезно знать о существующих агентах знаний для повторного использования или именования новых агентов.

# List knowledge agents
GET https://{{search-url}}/agents?api-version=2025-05-01-preview
   Content-Type: application/json
   Authorization: Bearer {{accessToken}}

Вы также можете вернуть агента по имени, чтобы ознакомиться с его JSON-определением.

# Get knowledge agent
GET https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview
   Content-Type: application/json
   Authorization: Bearer {{accessToken}}

Создание агента знаний

Агент знаний представляет соединение между моделью, развернутой в Azure OpenAI, и целевым индексом в службе "Поиск искусственного интеллекта Azure". Параметры модели устанавливают подключение. Параметры индекса устанавливают значения по умолчанию, которые сообщают о выполнении запроса и ответе.

Чтобы создать агент, используйте REST API плоскости данных 2025-05-01-preview или пакет предварительной версии SDK Azure, предоставляющий эквивалентную функциональность.

@search-url=<YOUR SEARCH SERVICE URL>
@agent-name=<YOUR AGENT NAME>
@index-name=<YOUR INDEX NAME>
@model-provider-url=<YOUR AZURE OPENAI RESOURCE URI>
@accessToken = <a long GUID>

# Create knowledge agent
PUT https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview
   Content-Type: application/json
   Authorization: Bearer {{accessToken}}

{
    "name" : "{{agent-name}}",
    "targetIndexes" : [
        {
            "indexName" : "{{index-name}}",
            "defaultRerankerThreshold": 2.5,
            "defaultIncludeReferenceSourceData": true,
            "defaultMaxDocsForReranker": 200
        }
    ],
    "models" : [ 
        {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{model-provider-url}}",
                "apiKey": "{{model-api-key}}",
                "deploymentId": "gpt-4o-mini",
                "modelName": "gpt-4o-mini"
            }
        }
    ],
    "requestLimits": {
        "maxOutputSize": 5000,
        "maxRuntimeInSeconds": 60
    },
    "encryptionKey": { }
}

Основные моменты:

name должен быть уникальным в коллекции агентов знаний и следовать рекомендациям по именованию объектов в службе "Поиск ИИ Azure".
targetIndexes требуется для создания агента знаний. В нем перечислены индексы поиска, которые могут использовать агент знаний. В настоящее время в предварительной версии выпуска targetIndexes массив может содержать только один индекс. Он должен иметь семантику по умолчанию (defaultConfiguration). Для получения более подробной информации, см. Проектирование индекса для агентного извлечения.
```
"semantic": {
    "defaultConfiguration": "my-default-semantic-config",
    "configurations": [ ]
}
```
defaultRerankerThreshold — это минимальная оценка семантического переборщика, которая приемлема для включения в ответ. Оценки ранжировщика варьируются от 1 до 4. Запланируйте изменение этого значения на основе тестирования и того, что работает для вашего содержимого.
defaultIncludeReferenceSourceData — это логическое значение, определяющее, включает ли ссылочная часть ответа исходные данные. Мы рекомендуем начать с того, чтобы это значение было установлено на true, если вы хотите сформировать собственный ответ, используя выходные данные поисковой системы. В противном случае, если вы хотите использовать выходные данные в строке ответа content , можно задать значение false.
defaultMaxDocsForReranker — максимальное количество документов, которые можно отправить в семантический рангировщик. Каждый вложенный запрос может передавать не более 50 документов в семантический реанктер, поэтому установка этого значения выше 50 создает дополнительные вложенные запросы до достижения максимального значения. Например, если задать для этого значения значение 200, для поддержки этого числа создаются четыре вложенных запроса. Этот
models указывает одно или несколько подключений к существующей модели gpt-4o или gpt-4o-mini. В настоящее время в этом предварительном выпуске модели могут содержать только одну модель, а поставщик моделей должен быть Azure OpenAI. Получение сведений о модели на портале Azure AI Foundry или из запроса командной строки. Вы можете использовать управление доступом на основе ролей вместо ключей API для подключения поиска ИИ Azure к модели. Дополнительные сведения см. в статье "Развертывание моделей Azure OpenAI с помощью Azure AI Foundry".

requestLimits позволяет управлять выходными данными, созданными во время извлечения, чтобы лучше управлять входными данными в LLM.
- maxOutputSize — максимальное количество маркеров в строке ответа content, где 5000 маркеров является минимальным и рекомендуемым значением, без явного максимума. Наиболее важные совпадения сохраняются, но общий ответ усечен до последнего полного документа, чтобы соответствовать бюджету токена.
- maxRuntimeInSeconds задает максимальное время обработки для всего запроса, включая как Azure OpenAI, так и Azure AI Search.
encryptionKey является необязательным. Включите определение ключа шифрования, если добавляете ключи, управляемые клиентом.

Подтверждение операций агента по управлению знаниями

Вызовите действие извлечения объекта агента знаний, чтобы подтвердить подключение модели и вернуть ответ. Используйте REST API плоскости данных 2025-05-01-preview или пакет предварительной версии Azure SDK, который предоставляет эквивалентную функциональность для этой задачи.

Замените "Каковы преимущества зрения?", на строку запроса, допустимую для индекса поиска.

# Send grounding request
POST https://{{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-05-01-preview
   Content-Type: application/json
   Authorization: Bearer {{accessToken}}

{
    "messages" : [
            {
                "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "You are a helpful assistant for Contoso Human Resources. You have access to a search index containing guidelines about health care coverage for Washington state. If you can't find the answer in the search, say you don't know." }
                ]
            },
            {
                "role" : "user",
                "content" : [
                  { "type" : "text", "text" : "What are my vision benefits?" }
                ]
            }
        ],
    "targetIndexParams" :  [
        { 
            "indexName" : "{{index-name}}",
            "filterAddOn" : "State eq 'WA'",
            "IncludeReferenceSourceData": true,
            "rerankerThreshold" : 2.5
            "maxDocsForReranker": 250
        } 
    ]
}

Дополнительные сведения об API извлечения и форме ответа см. в статье "Получение данных" с помощью агента знаний в службе "Поиск ИИ Azure".

Удаление агента

Если агент больше не нужен или необходимо перестроить его в службе поиска, используйте этот запрос для удаления текущего объекта.

# Delete agent
DELETE https://{{search-url}}/agents/{{agent-name}}?api-version=2025-05-01-preview
   Authorization: Bearer {{accessToken}}