Получение данных с помощью базы знаний в службе "Поиск ИИ Azure"

В агентском конвейере многоэтапного извлечения выполнение запроса осуществляется через действие извлечения на базе знаний, что инициирует параллельную обработку запросов. Эта структура запроса обновляется для новой версии 2025-11-01-preview, которая представляет критические изменения из предыдущих предварительных версий. Сведения о критических изменениях см. в статье "Миграция кода извлечения агента".

Статья объясняет, как выполнить настройку операции извлечения. Он также охватывает три компонента ответа извлечения:

• извлеченный ответ для модели LLM
• ссылки на результаты
• Активность запроса

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

Предпосылки

• Поддерживаемый источник знаний, который упаковывает индекс, доступный для поиска, или указывает на внешний источник для извлечения собственных данных.

• База знаний представляет один или несколько источников знаний, а также модель завершения чата, если требуется интеллектуальное планирование запросов и формулировка ответов.

• Поиск по искусственному интеллекту Azure в любом регионе, который предоставляет агентское извлечение.

• Разрешения для поиска ИИ Azure. Роли для получения содержимого включают средство чтения данных индекса поиска для выполнения запросов. Чтобы поддерживать исходящий вызов из службы поиска в модель завершения чата, необходимо настроить управляемое удостоверение для службы поиска и иметь разрешения пользователя Cognitive Services в ресурсе Azure OpenAI. Дополнительные сведения о локальном тестировании и получении маркеров доступа см. в кратком руководстве по подключению без ключей.

• Требования к версии API. Чтобы создать или использовать базу знаний, используйте REST API уровня данных 2025-11-01-preview. Кроме того, используйте пакет предварительной версии пакета SDK Azure, предоставляющий API базы знаний: Python, .NET, Java.

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

Настройка действия извлечения

Действие извлечения указывается в базе знаний. База знаний имеет один или несколько источников знаний. Получение может возвращать ответ, синтезированный на естественном языке, или необработанные фрагменты из основных источников знаний.

• Просмотрите определение базы знаний, чтобы понять, какие источники знаний находятся в области.

• Просмотрите источники знаний, чтобы понять их параметры и конфигурацию.

• Используйте REST API плоскости данных 2025-11-01-preview или предварительную версию Azure SDK для получения.

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

Извлечение из индекса поиска

Для источников знаний, предназначенных для индекса поиска, все searchable поля находятся в области выполнения запроса. Если индекс содержит векторные поля, ваш индекс должен иметь допустимое определение векторизатора, чтобы механизм агентного поиска мог векторизировать входные данные запроса. В противном случае поля векторов игнорируются. Подразумеваемый тип запроса — semanticнет режима поиска.

Входные данные для пути поиска — это история чатов на естественном языке, где массив messages содержит разговор. Сообщения поддерживаются только в том случае, если усилие по рассуждению для извлечения является низким или средним.

@search-url=<YOUR SEARCH SERVICE URL>
@accessToken=<YOUR PERSONAL ID>

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

{
    "messages" : [
            {
                "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "You can answer questions about the Earth at night.
                    Sources have a JSON format with a ref_id that must be cited in the answer.
                    If you do not have the answer, respond with 'I do not know'." }
                ]
            },
            {
                "role" : "user",
                "content" : [
                  { "type" : "text", "text" : "Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?" }
                ]
            }
        ],
  "knowledgeSourceParams": [
    {
      "filterAddOn": null,
      "knowledgeSourceName": "earth-at-night-blob-ks",
      "kind": "searchIndex"
    }
  ]
}

Responses

Извлечение успешно возвращает код состояния 200 OK. Если базе знаний не удается извлечь данные из одного или нескольких источников знаний, возвращается код состояния 206 Partial Content, и ответ включает только результаты из источников, из которых удалось извлечь данные. Сведения о частичном ответе отображаются в виде ошибок в массиве действий.

Получение параметров

Примеры

Запросы на получение данных могут различаться в зависимости от источников знаний и того, хотите ли вы изменить конфигурацию по умолчанию. Ниже приведено несколько примеров, которые иллюстрируют диапазон запросов.

Пример: Переопределите параметры обработки по умолчанию и установите ограничения на запросы

В этом примере указывается формулировка ответа, поэтому retrievalReasoningEffort должна быть "низкая" или "средняя".

POST {{url}}/knowledgebases/kb-override/retrieve?api-version={{api-version}}
api-key: {{key}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What companies are in the financial sector?" }
            ]
        }
    ],
    "retrievalReasoningEffort": { "kind": "low" },
    "outputMode": "answerSynthesis",
    "maxRuntimeInSeconds": 30,
    "maxOutputSize": 6000
}

Пример. Установка ссылок для каждого источника знаний

В этом примере используются усилия для рассуждений по умолчанию, указанные в базе знаний. Основное внимание в этом примере уделяется спецификации объема информации, включаемой в ответ.

POST {{url}}/knowledgebases/kb-medium-example/retrieve?api-version={{api-version}}
api-key: {{key}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What companies are in the financial sector?" }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "demo-financials-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": true
        },
        {
            "knowledgeSourceName": "demo-communicationservices-ks",
            "kind": "searchIndex",
            "includeReferences": false,
            "includeReferenceSourceData": false
        },
        {
            "knowledgeSourceName": "demo-healthcare=ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": false,
            "alwaysQuerySource": true
        }
    ]
}

Пример: минимальные усилия для размышлений

В этом примере нет модели завершения чата для интеллектуального планирования запросов или формулировки ответов. Строка запроса передается в агентский поисковый движок для поиска ключевых слов или гибридного поиска.

POST {{url}}/knowledgebases/kb-minimal/retrieve?api-version={{api-version}}
api-key: {{key}}
Content-Type: application/json

{
    "intents": [
        {
            "type": "semantic",
            "search": "what is a brokerage"
        }
    ]
}

Просмотр извлеченного ответа

Извлеченный ответ представляет собой единую строку, которая обычно передается в LLM, которые используют её в качестве опорных данных, чтобы сформулировать ответ. Вызов API к LLM включает в себя единую строку и инструкции модели, например, следует ли использовать основы исключительно или в качестве дополнения.

Текст ответа также структурирован в формате стиля сообщения чата. В настоящее время в этом выпуске предварительной версии содержимое сериализуется в формате JSON.

"response": [
    {
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "[{\"ref_id\":0,\"title\":\"Urban Structure\",\"terms\":\"Location of Phoenix, Grid of City Blocks, Phoenix Metropolitan Area at Night\",\"content\":\"<content chunk redacted>\"}]"
            }
        ]
    }
]

Ключевые моменты:

• content.text — это массив JSON. Это одна строка, состоящая из наиболее релевантных документов (или блоков), найденных в индексе поиска, учитывая входные данные журнала запросов и чата. Этот массив – это базовые данные, которые модель завершения чата использует для формирования ответа на вопрос пользователя.

  Эта часть ответа состоит из 200 блоков или меньше, исключая любые результаты, которые не соответствуют минимальному пороговому значению 2,5 оценки повторного ранга.

  Строка начинается с идентификатора ссылки блока (используемого для ссылок) и любых полей, указанных в семантической конфигурации целевого индекса. В этом примере следует предположить, что семантическая конфигурация в целевом индексе имеет поле "title", поле "термины" и поле "content".

• content.typeимеет одно допустимое значение в этой предварительной версии: text

Анализ массива действий

Массив действий выводит план запроса, который помогает отслеживать операции, выполняемые при выполнении запроса. Она также обеспечивает прозрачность работы, чтобы понять последствия выставления счетов и частоту вызовов ресурсов.

Выходные данные включают следующие компоненты.

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

Выходные данные также содержат следующие сведения:

• Вложенные запросы, отправленные в конвейер извлечения.
• Ошибки, возникающие из-за любых сбоев в извлечении, таких как недоступность источников знаний.

Ниже приведен пример массива действий.

  "activity": [
    {
      "type": "modelQueryPlanning",
      "id": 0,
      "inputTokens": 2302,
      "outputTokens": 109,
      "elapsedMs": 2396
    },
    {
      "type": "searchIndex",
      "id": 1,
      "knowledgeSourceName": "demo-financials-ks",
      "queryTime": "2025-11-04T19:25:23.683Z",
      "count": 26,
      "elapsedMs": 1137,
      "searchIndexArguments": {
        "search": "List of companies in the financial sector according to SEC GICS classification",
        "filter": null,
        "sourceDataFields": [ ],
        "searchFields": [ ],
        "semanticConfigurationName": "en-semantic-config"
      }
    },
    {
      "type": "searchIndex",
      "id": 2,
      "knowledgeSourceName": "demo-healthcare-ks",
      "queryTime": "2025-11-04T19:25:24.186Z",
      "count": 17,
      "elapsedMs": 494,
      "searchIndexArguments": {
        "search": "List of companies in the financial sector according to SEC GICS classification",
        "filter": null,
        "sourceDataFields": [ ],
        "searchFields": [ ],
        "semanticConfigurationName": "en-semantic-config"
      }
    },
    {
      "type": "agenticReasoning",
      "id": 3,
      "retrievalReasoningEffort": {
        "kind": "low"
      },
      "reasoningTokens": 103368
    },
    {
      "type": "modelAnswerSynthesis",
      "id": 4,
      "inputTokens": 5821,
      "outputTokens": 344,
      "elapsedMs": 3837
    }
  ]

Просмотр массива ссылок

Массив references является прямой ссылкой на основные данные основы и включает sourceData, используемые для формирования ответа. Документы состоят из каждого найденного документа, который был семантически ранжирован агентским механизмом извлечения. Поля в списке sourceData включают в себя id и семантические поля: title, terms, content.

Это id идентификатор ссылки для элемента в определенном ответе. Это не ключ документа в индексе поиска. Он используется для предоставления ссылок.

Цель этого массива — предоставить структуру стиля сообщений чата для простой интеграции. Например, если вы хотите сериализовать результаты в другую структуру или необходимо программное преобразование данных перед их возвращением пользователю.

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

Ниже приведен пример массива ссылок.

  "references": [
    {
      "type": "AzureSearchDoc",
      "id": "0",
      "activitySource": 2,
      "docKey": "earth_at_night_508_page_104_verbalized",
      "sourceData": null
    },
    {
      "type": "AzureSearchDoc",
      "id": "1",
      "activitySource": 2,
      "docKey": "earth_at_night_508_page_105_verbalized",
      "sourceData": null
    }
  ]

Связанный контент

• Агентское извлечение в Azure AI Search
• Agentic RAG: создание системы извлечения, поддерживающей логическое построение, с использованием Azure AI Search (видео на YouTube)
• Демонстрация Azure OpenAI с агентическим извлечением