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

Источник знаний индекса поиска указывает подключение к индексу поиска Azure AI, который предоставляет содержимое для поиска в агентном конвейере извлечения. Источники знаний создаются независимо, ссылаются на базу знаний и используются в качестве исходных данных, когда агент или чат-бот вызывает действие извлечения во время запроса.

Предпосылки

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

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

• Последняя предварительная версия клиентской библиотекиAzure.Search.Documents для пакета SDK для .NET.

• Разрешение на создание и использование объектов в службе "Поиск ИИ Azure". Рекомендуем использовать доступ на основе ролей, но вы можете использовать ключи API, если назначение роли невозможно. Дополнительные сведения см. в разделе "Подключение к службе поиска".

Проверка существующих источников знаний

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

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

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

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

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

Следующий код JSON является примером ответа для источника знаний индекса поиска. Обратите внимание, что источник знаний указывает одно имя индекса и поля в индексе для включения в запрос.

{
  "SearchIndexParameters": {
    "SearchIndexName": "earth-at-night",
    "SourceDataFields": [
      {
        "Name": "id"
      },
      {
        "Name": "page_chunk"
      },
      {
        "Name": "page_number"
      }
    ],
    "SearchFields": [],
    "SemanticConfigurationName": "semantic-config"
  },
  "Name": "earth-knowledge-source",
  "Description": null,
  "EncryptionKey": null,
  "ETag": "<redacted>"
}

Создание источника знаний

Выполните следующий код, чтобы создать источник знаний индекса поиска.

using Azure.Search.Documents.Indexes.Models;

// Create the knowledge source
var indexKnowledgeSource = new SearchIndexKnowledgeSource(
    name: knowledgeSourceName,
    searchIndexParameters: new SearchIndexKnowledgeSourceParameters(searchIndexName: indexName)
    {
        SourceDataFields = { new SearchIndexFieldReference(name: "id"), new SearchIndexFieldReference(name: "page_chunk"), new SearchIndexFieldReference(name: "page_number") }
    }
);

await indexClient.CreateOrUpdateKnowledgeSourceAsync(indexKnowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSourceName}' created or updated successfully.");

Свойства, относящиеся к источнику

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

Назначение базе знаний

Если вы удовлетворены источником знаний, перейдите к следующему шагу: укажите источник знаний в базе знаний.

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

Удаление источника знаний

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

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

Удаление источника знаний:

1. Получите список всех баз знаний в службе поиска.

   # Get knowledge bases
   import requests
   import json
   
   endpoint = "{search_url}/knowledgebases"
   params = {"api-version": "2025-11-01-preview", "$select": "name"}
   headers = {"api-key": "{api_key}"}
   
   response = requests.get(endpoint, params = params, headers = headers)
   print(json.dumps(response.json(), indent = 2))
   

   Пример ответа может выглядеть следующим образом:

    {
        "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
        "value": [
        {
            "name": "my-kb"
        },
        {
            "name": "my-kb-2"
        }
        ]
    }
   

2. Получите отдельное определение базы знаний для проверки ссылок на источники знаний.

   # Get a knowledge base definition
   import requests
   import json
   
   endpoint = "{search_url}/knowledgebases/{knowledge_base_name}"
   params = {"api-version": "2025-11-01-preview"}
   headers = {"api-key": "{api_key}"}
   
   response = requests.get(endpoint, params = params, headers = headers)
   print(json.dumps(response.json(), indent = 2))
   

   Пример ответа может выглядеть следующим образом:

    {
      "name": "my-kb",
      "description": null,
      "retrievalInstructions": null,
      "answerInstructions": null,
      "outputMode": null,
      "knowledgeSources": [
        {
          "name": "my-blob-ks",
        }
      ],
      "models": [],
      "encryptionKey": null,
      "retrievalReasoningEffort": {
        "kind": "low"
      }
    }
   

3. Удалите базу знаний или обновите базу знаний, чтобы удалить источник знаний при наличии нескольких источников. В этом примере показано удаление.

   # Delete a knowledge base
   from azure.core.credentials import AzureKeyCredential 
   from azure.search.documents.indexes import SearchIndexClient
   
   index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
   index_client.delete_knowledge_base("knowledge_base_name")
   print(f"Knowledge base deleted successfully.")
   

4. Удалите источник знаний.

   # Delete a knowledge source
   from azure.core.credentials import AzureKeyCredential 
   from azure.search.documents.indexes import SearchIndexClient
   
   index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
   index_client.delete_knowledge_source("knowledge_source_name")
   print(f"Knowledge source deleted successfully.")
   

В службе "Поиск ИИ Azure" база знаний — это объект верхнего уровня, который управляет агентическим извлечением. Он определяет, какие источники знаний запрашивать и поведение по умолчанию для операций извлечения. Во время выполнения запроса метод извлечения нацелен на базу знаний для запуска настроенного конвейера извлечения.

База знаний указывает:

• Один или несколько источников знаний, указывающих на доступный для поиска контент.
• Необязательный LLM, предоставляющий возможности для планирования запросов и формулировки ответов.
• Задача рассуждения при извлечении, которая определяет, вызывается ли LLM, и управляет затратами, задержкой и качеством.
• Пользовательские свойства, управляющие маршрутизацией, выбором источника, форматом вывода и шифрованием объектов.

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

Предпосылки

• Поиск по искусственному интеллекту Azure в любом регионе, который предоставляет агентское извлечение. Необходимо включить семантику ранжирования. Если вы используете управляемое удостоверение для доступа на основе ролей к развернутым моделям, служба поиска должна находиться на тарифе "Базовый" или выше.

• Azure OpenAI с поддерживаемым развертыванием LLM .

• Один или несколько источников знаний в службе поиска.

• Разрешение на создание и использование объектов в службе "Поиск ИИ Azure". Рекомендуется использовать доступ на основе ролей. Участник службы поиска может создавать базу знаний и управлять ею. Средство чтения данных индекса поиска может выполнять запросы. Кроме того, можно использовать ключи API , если назначение роли невозможно. Дополнительные сведения см. в разделе "Подключение к службе поиска".

• Последняя предварительная версия клиентской библиотекиazure-search-documents для Python.

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

Используйте одну из следующих LLM из Azure OpenAI или эквивалентную модель с открытым кодом. Инструкции по развертыванию см. в статье "Развертывание моделей Azure OpenAI с помощью Microsoft Foundry".

• gpt-4o
• gpt-4o-mini
• gpt-4.1
• gpt-4.1-nano
• gpt-4.1-mini
• gpt-5
• gpt-5-nano
• gpt-5-mini

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

Для поиска ИИ Azure требуется доступ к LLM из Azure OpenAI. Мы рекомендуем идентификатор Microsoft Entra для проверки подлинности и доступа на основе ролей для авторизации. Для назначения ролей необходимо быть владельцем или администратором доступа пользователей . Если роли не подходят, используйте аутентификацию на основе ключей.

Проверка существующих баз знаний

Знание существующих баз знаний полезно для повторного использования или именования новых объектов. Все агенты знаний 2025-08-01-preview возвращаются в коллекции баз знаний.

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

# List knowledge bases by name
import requests
import json

endpoint = "{search_url}/knowledgebases"
params = {"api-version": "2025-11-01-preview", "$select": "name"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

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

# Get a knowledge base definition
import requests
import json

endpoint = "{search_url}/knowledgebases/{knowledge_base_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

Следующий код JSON является примером ответа для базы знаний.

{
  "name": "my-kb",
  "description": "A sample knowledge base.",
  "retrievalInstructions": null,
  "answerInstructions": null,
  "outputMode": null,
  "knowledgeSources": [
    {
      "name": "my-blob-ks"
    }
  ],
  "models": [],
  "encryptionKey": null,
  "retrievalReasoningEffort": {
    "kind": "low"
  }
}

Создание базы знаний

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

База знаний подключает источники знаний (содержимое, доступное для поиска) к развертыванию LLM из Azure OpenAI. Свойства LLM устанавливают подключение, а свойства в источнике знаний устанавливают значения по умолчанию, которые сообщают о выполнении запроса и ответе.

Выполните следующий код, чтобы создать базу знаний.

# Create a knowledge base
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import KnowledgeBase, KnowledgeBaseAzureOpenAIModel, KnowledgeSourceReference, AzureOpenAIVectorizerParameters, KnowledgeRetrievalOutputMode, KnowledgeRetrievalLowReasoningEffort

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

aoai_params = AzureOpenAIVectorizerParameters(
    resource_url = "aoai_endpoint",
    deployment_name = "aoai_gpt_deployment",
    model_name = "aoai_gpt_model",
)

knowledge_base = KnowledgeBase(
    name = "my-kb",
    description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    retrieval_instructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    answer_instructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
    output_mode = KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
    knowledge_sources = [
        KnowledgeSourceReference(name = "hotels-ks"),
        KnowledgeSourceReference(name = "earth-at-night-ks"),
    ],
    models = [KnowledgeBaseAzureOpenAIModel(azure_open_ai_parameters = aoai_params)],
    encryption_key = None,
    retrieval_reasoning_effort = KnowledgeRetrievalLowReasoningEffort,
)

index_client.create_or_update_knowledge_base(knowledge_base)
print(f"Knowledge base '{knowledge_base.name}' created or updated successfully.")

Свойства базы знаний

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

Запрос к базе знаний

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

Замените "Где океан выглядит зеленым?" строкой запроса, допустимой для источников знаний.

# Send grounding request
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import KnowledgeBaseMessage, KnowledgeBaseMessageTextContent, KnowledgeBaseRetrievalRequest, RemoteSharePointKnowledgeSourceParams

kb_client = KnowledgeBaseRetrievalClient(endpoint = "search_url", knowledge_base_name = "knowledge_base_name", credential = AzureKeyCredential("api_key"))

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role = "assistant",
            content = [KnowledgeBaseMessageTextContent(text = "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know.")]
        ),
        KnowledgeBaseMessage(
            role = "user",
            content = [KnowledgeBaseMessageTextContent(text = "Where does the ocean look green?")]
        ),
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name = "earth-at-night-ks",
            include_references = True,
            include_reference_source_data = True,
            always_query_source = False,
        )
    ],
    include_activity = True,
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

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

• messages требуется, но вы можете запустить этот пример, используя только user роль, которая предоставляет запрос.

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

Ответ на пример запроса может выглядеть следующим образом:

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

Удаление базы знаний

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

# Delete a knowledge base
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_base("knowledge_base_name")
print(f"Knowledge base deleted successfully.")

В службе "Поиск ИИ Azure" база знаний — это объект верхнего уровня, который управляет агентическим извлечением. Он определяет, какие источники знаний запрашивать и поведение по умолчанию для операций извлечения. Во время выполнения запроса метод извлечения нацелен на базу знаний для запуска настроенного конвейера извлечения.

База знаний указывает:

• Один или несколько источников знаний, указывающих на доступный для поиска контент.
• Необязательный LLM, предоставляющий возможности для планирования запросов и формулировки ответов.
• Задача рассуждения при извлечении, которая определяет, вызывается ли LLM, и управляет затратами, задержкой и качеством.
• Пользовательские свойства, управляющие маршрутизацией, выбором источника, форматом вывода и шифрованием объектов.

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

Предпосылки

• Поиск по искусственному интеллекту Azure в любом регионе, который предоставляет агентское извлечение. Необходимо включить семантику ранжирования. Если вы используете управляемое удостоверение для доступа на основе ролей к развернутым моделям, служба поиска должна находиться на тарифе "Базовый" или выше.

• Azure OpenAI с поддерживаемым развертыванием LLM .

• Один или несколько источников знаний в службе поиска.

• Разрешение на создание и использование объектов в службе "Поиск ИИ Azure". Рекомендуется использовать доступ на основе ролей. Участник службы поиска может создавать базу знаний и управлять ею. Средство чтения данных индекса поиска может выполнять запросы. Кроме того, можно использовать ключи API , если назначение роли невозможно. Дополнительные сведения см. в разделе "Подключение к службе поиска"

• Последняя предварительная версия клиентской библиотекиAzure.Search.Documents для пакета SDK для .NET.

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

Используйте одну из следующих LLM из Azure OpenAI или эквивалентную модель с открытым кодом. Инструкции по развертыванию см. в статье "Развертывание моделей Azure OpenAI с помощью Microsoft Foundry".

• gpt-4o
• gpt-4o-mini
• gpt-4.1
• gpt-4.1-nano
• gpt-4.1-mini
• gpt-5
• gpt-5-nano
• gpt-5-mini

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

Для поиска ИИ Azure требуется доступ к LLM из Azure OpenAI. Мы рекомендуем идентификатор Microsoft Entra для проверки подлинности и доступа на основе ролей для авторизации. Для назначения ролей необходимо быть владельцем или администратором доступа пользователей . Если роли не подходят, используйте аутентификацию на основе ключей.

Проверка существующих баз знаний

База знаний — это объект верхнего уровня, который можно использовать повторно. Знание существующих баз знаний полезно для повторного использования или именования новых объектов. Все агенты знаний 2025-08-01-preview возвращаются в коллекции баз знаний.

Используйте базы знаний — список (REST API) для перечисления баз знаний по имени и типу.

# List knowledge bases
GET {{search-url}}/knowledgebases?api-version=2025-11-01-preview&$select=name
Content-Type: application/json
api-key: {{search-api-key}}

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

# Get knowledge base
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

Следующий код JSON является примером ответа для базы знаний.

{
  "name": "my-kb",
  "description": "A sample knowledge base.",
  "retrievalInstructions": null,
  "answerInstructions": null,
  "outputMode": null,
  "knowledgeSources": [
    {
      "name": "my-blob-ks"
    }
  ],
  "models": [],
  "encryptionKey": null,
  "retrievalReasoningEffort": {
    "kind": "low"
  }
}

Создание базы знаний

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

База знаний подключает источники знаний (содержимое, доступное для поиска) к развертыванию LLM из Azure OpenAI. Свойства LLM устанавливают подключение, а свойства в источнике знаний устанавливают значения по умолчанию, которые сообщают о выполнении запроса и ответе.

Используйте базы знаний— создание или обновление (REST API) для формирования запроса.

# Create a knowledge base
PUT {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "name" : "my-kb",
    "description": "This knowledge base handles questions directed at two unrelated sample indexes.",
    "retrievalInstructions": "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    "answerInstructions": null,
    "outputMode": "answerSynthesis",
    "knowledgeSources": [
        {
            "name": "hotels-ks"
        },
        {
            "name": "earth-at-night-ks"
        }
    ],
    "models" : [ 
        {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{model-provider-url}}",
                "apiKey": "{{model-api-key}}",
                "deploymentId": "gpt-4.1-mini",
                "modelName": "gpt-4.1-mini"
            }
        }
    ],
    "encryptionKey": null,
    "retrievalReasoningEffort": {
        "kind": "low"
    }
}

Свойства базы знаний

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

Запрос к базе знаний

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

Используйте извлечение знаний — получение (REST API) для формирования запроса. Замените "Где океан выглядит зеленым?" строкой запроса, допустимой для источников знаний.

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

{
    "messages" : [
        { "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know." }
                ]
        },
        {
            "role" : "user",
            "content" : [
                {
                    "text" : "Where does the ocean look green?",
                    "type" : "text"
                }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "earth-at-night-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": true,
            "alwaysQuerySource": false
        }
  ]
}

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

• messages требуется, но вы можете запустить этот пример, используя только user роль, которая предоставляет запрос.

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

Ответ на пример запроса может выглядеть следующим образом:

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

Удаление базы знаний

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

# Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{search-api-key}}