Поделиться через


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

Замечание

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

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

Предпосылки

Замечание

Хотя вы можете использовать портал Azure для создания источников знаний для поискового индекса, на портале используется версия 2025-08-01-preview, которая использует предыдущую терминологию "knowledge agent" и не поддерживает все возможности версии 2025-11-01-preview. Сведения о критических изменениях см. в статье "Миграция кода извлечения агента".

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

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

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

// 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.");

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

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

Имя Description Тип Возможно изменение Обязательно
Name Имя источника знаний, которое должно быть уникальным в коллекции источников знаний и следуйте рекомендациям по именованию объектов в службе "Поиск ИИ Azure". String нет Да
Description Описание источника знаний. String Да нет
EncryptionKey Управляемый клиентом ключ для шифрования конфиденциальной информации как в источнике знаний, так и в созданных объектах. Object Да нет
SearchIndexParameters Параметры, относящиеся к источникам знаний индекса поиска: search_index_name, SemanticConfigurationName, SourceDataFieldsи SearchFields. Object Да Да
SearchIndexName Имя существующего индекса поиска. String Да Да
SemanticConfigurationName Переопределяет семантику по умолчанию для индекса поиска. String Да нет
SourceDataFields Поля индекса, возвращаемые при указании include_reference_source_data в определении базы знаний. Эти поля используются для ссылок и должны быть retrievable. Примеры включают имя документа, имя файла, номера страниц или номера глав. Массив Да нет
SearchFields Поля индекса для конкретного поиска. Если поля не указаны, производится поиск по всем полям. Массив Да нет

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

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

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

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

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

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

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

  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.")
    

Замечание

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

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

Предпосылки

Замечание

Хотя вы можете использовать портал Azure для создания источников знаний для поискового индекса, на портале используется версия 2025-08-01-preview, которая использует предыдущую терминологию "knowledge agent" и не поддерживает все возможности версии 2025-11-01-preview. Сведения о критических изменениях см. в статье "Миграция кода извлечения агента".

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

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

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

# List knowledge sources by name and type
import requests
import json

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

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

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

# Get a knowledge source definition
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_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-search-index-ks",
  "kind": "searchIndex",
  "description": "A sample search index knowledge source.",
  "encryptionKey": null,
  "searchIndexParameters": {
    "searchIndexName": "my-search-index",
    "semanticConfigurationName": null,
    "sourceDataFields": [],
    "searchFields": []
  }
}

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

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

# Create a search index knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import SearchIndexKnowledgeSource, SearchIndexKnowledgeSourceParameters, SearchIndexFieldReference

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

knowledge_source = SearchIndexKnowledgeSource(
    name = "my-search-index-ks",
    description= "This knowledge source pulls from an existing index designed for agentic retrieval.",
    encryption_key = None,
    search_index_parameters = SearchIndexKnowledgeSourceParameters(
        search_index_name = "search_index_name",
        semantic_configuration_name = "semantic_configuration_name",
        source_data_fields = [
            SearchIndexFieldReference(name="description"),
            SearchIndexFieldReference(name="category"),
        ],
        search_fields = [
            SearchIndexFieldReference(name="id")
        ],
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

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

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

Имя Description Тип Возможно изменение Обязательно
name Имя источника знаний, которое должно быть уникальным в коллекции источников знаний и следуйте рекомендациям по именованию объектов в службе "Поиск ИИ Azure". String нет Да
description Описание источника знаний. String Да нет
encryption_key Управляемый клиентом ключ для шифрования конфиденциальной информации как в источнике знаний, так и в созданных объектах. Object Да нет
search_index_parameters Параметры, относящиеся к источникам знаний индекса поиска: search_index_name, semantic_configuration_name, source_data_fieldsи search_fields. Object Да Да
search_index_name Имя существующего индекса поиска. String Да Да
semantic_configuration_name Переопределяет семантику по умолчанию для индекса поиска. String Да нет
source_data_fields Поля индекса, возвращаемые при указании include_reference_source_data в определении базы знаний. Эти поля используются для ссылок и должны быть retrievable. Примеры включают имя документа, имя файла, номера страниц или номера глав. Массив Да нет
search_fields Поля индекса для конкретного поиска. Если поля не указаны, производится поиск по всем полям. Массив Да нет

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

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

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

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

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

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

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

  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.")
    

Замечание

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

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

Предпосылки

Замечание

Хотя вы можете использовать портал Azure для создания источников знаний для поискового индекса, на портале используется версия 2025-08-01-preview, которая использует предыдущую терминологию "knowledge agent" и не поддерживает все возможности версии 2025-11-01-preview. Сведения о критических изменениях см. в статье "Миграция кода извлечения агента".

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

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

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

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version=2025-11-01-preview&$select=name,kind
api-key: {{api-key}}

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

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

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

{

  "name": "my-search-index-ks",
  "kind": "searchIndex",
  "description": "A sample search index knowledge source.",
  "encryptionKey": null,
  "searchIndexParameters": {
    "searchIndexName": "my-search-index",
    "semanticConfigurationName": null,
    "sourceDataFields": [],
    "searchFields": []
  }
}

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

Используйте Источники Знаний - Создать или обновить (REST API) для создания источника знаний для поискового индекса.

POST {{search-url}}/knowledgesources/my-search-index-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
    "name": "my-search-index-ks",
    "kind": "searchIndex",
    "description": "This knowledge source pulls from an existing index designed for agentic retrieval.",
    "encryptionKey": null,
    "searchIndexParameters": {
        "searchIndexName": "<YOUR INDEX NAME>",
        "semanticConfigurationName": "my-semantic-config",
        "sourceDataFields": [
          { "name": "description" },
          { "name": "category" }
        ],
        "searchFields": [
          { "name": "*" }
        ]
    }
}

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

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

Имя Description Тип Возможно изменение Обязательно
name Имя источника знаний, которое должно быть уникальным в коллекции источников знаний и следуйте рекомендациям по именованию объектов в службе "Поиск ИИ Azure". String нет Да
kind Тип источника знаний, в данном случае searchIndex. String нет Да
description Описание источника знаний. String Да нет
encryptionKey Управляемый клиентом ключ для шифрования конфиденциальной информации как в источнике знаний, так и в созданных объектах. Object Да нет
searchIndexParameters Параметры, относящиеся к источникам знаний индекса поиска: searchIndexName, semanticConfigurationName, sourceDataFieldsи searchFields. Object Да Да
searchIndexName Имя существующего индекса поиска. String Да Да
semanticConfigurationName Переопределяет семантику по умолчанию для индекса поиска. String Да нет
sourceDataFields Поля индекса, возвращаемые при указании includeReferenceSourceData в определении базы знаний. Эти поля используются для ссылок и должны быть retrievable. Примеры включают имя документа, имя файла, номера страниц или номера глав. Массив Да нет
searchFields Поля индекса для конкретного поиска. Если поля не указаны, производится поиск по всем полям. Массив Да нет

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

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

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

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

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

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

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

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

    ### Get knowledge bases
    GET {{search-endpoint}}/knowledgebases?api-version=2025-11-01-preview&$select=name
    api-key: {{api-key}}
    

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

     {
         "@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
    GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
    api-key: {{api-key}}
    

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

     {
       "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
    DELETE {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
    api-key: {{api-key}}
    
  4. Удалите источник знаний.

    ### Delete a knowledge source
    DELETE {{search-endpoint}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
    api-key: {{api-key}}