Облачная платформаEvolution

Создание чанков с помощью Public API

Эта статья полезна?

С помощью этого руководства вы научитесь создавать чанки в базе знаний с помощью Managed RAG API, просматривать получившиеся чанки и отправлять к ним запросы с помощью Search API.

Вы будете использовать следующие сервисы:

Шаги:

  1. Создайте базу знаний.

  2. Создайте чанк с помощью API.

  3. Создайте чанк с пользовательскими метаданными.

  4. Посмотрите получившиеся чанки.

  5. Отправьте поисковый запрос.

  6. Отправьте поисковый запрос с фильтром.

Перед началом работы

  1. Создайте бакет и папку внутри него.

  2. Создайте сервисный аккаунт с ролью managed-rag.admin.

  3. Сгенерируйте ключи доступа для сервисного аккаунта.

    Сохраните Key ID (логин) и Key Secret (пароль).

  4. Получите токен для доступа к API с помощью curl-запроса:

    curl --location 'https://iam.api.cloud.ru/api/v1/auth/token' \
    --header 'Content-Type: application/json' \
    --data '{
    "keyId": "<key_id>",
    "secret": "<secret>"
    }'

    Где:

    • keyId — Key ID (логин) ключа доступа;

    • secret — Key Secret (пароль) ключа доступа.

    Сохраните токен. Он понадобится для всех запросов к API.

1. Создайте базу знаний

  1. Перейдите в AI Factory → Managed RAG.

  2. Нажмите Создать базу знаний.

  3. В поле Название введите api-chunks-kb.

  4. Активируйте опцию Создать первую версию.

  5. В поле Название версии введите api-chunks-version.

  6. В блоке Источники из S3 нажмите Выбрать и выберите ранее созданную папку.

  7. В поле Расширения документов выберите расширение txt.

  8. Нажмите Создать.

Дождитесь, когда версия базы знаний перейдет в статус «Активная».

2. Создайте чанк

Отправьте запрос Create:

curl -X POST 'https://managed-rag.api.cloud.ru/v2/chunks \
-H "Content-Type: application/json" \
-H 'Authorization: Bearer <access_token> \
-d '{
"knowledgebase_id": "<knowledgebase_id>",
"knowledgebase_version_id": "<knowledgebase_version_id>",
"project_id": "<project_id>",
"chunks": [
{
"chunk_id": "<chunk_id>",
"type": "CONTENT_TYPE_TEXT",
"content": "my first chunk."
}
]
}'

Где:

  • <access_token> — токен доступа, полученный перед началом работы.

  • <knowledgebase_id> — идентификатор базы знаний.

  • <knowledgebase_version> — идентификатор версии базы знаний.

  • <project_id> — идентификатор проекта.

  • <chunk_id>— идентификатор чанка. Введите желаемый идентификатор или оставьте поле пустым для автоматической генерации.

  • type — тип содержимого чанка. В данном случае используется текстовое содержимое.

  • content — содержимое чанка.

Примечание

Вы можете создавать до 10 чанков в одном запросе.

3. Создайте чанк с пользовательскими метаданными

Запрос на создание чанка с пользовательскими метаданными отличается от стандартного запроса добавлением объекта metadata.

Отправьте запрос Create:

curl -X POST 'https://managed-rag.api.cloud.ru/v2/chunks \
-H "Content-Type: application/json" \
-H 'Authorization: Bearer <access_token> \
-d '{
"knowledgebase_id": "<knowledgebase_id>",
"knowledgebase_version_id": "<knowledgebase_version_id>",
"project_id": "<project_id>",
"chunks": [
{
"chunk_id": "<chunk_id>",
"type": "CONTENT_TYPE_TEXT",
"content": "my second chunk.",
"metadata": {
"user key": "user value"
}
}
]
}'

Где:

  • <access_token> — токен доступа, полученный перед началом работы.

  • <knowledgebase_id> — идентификатор базы знаний.

  • <knowledgebase_version> — идентификатор версии базы знаний.

  • <project_id> — идентификатор проекта.

  • <chunk_id>— идентификатор чанка. Введите желаемый идентификатор или оставьте поле пустым для автоматической генерации.

  • type — тип содержимого чанка. В данном случае используется текстовое содержимое.

  • content — содержимое чанка.

  • metadata — объект с пользовательскими метаданными.

  • user key — ключ метаданных.

  • user value — значение метаданных.

Вы можете использовать больше одной пары ключ:значение.

4. Посмотрите получившиеся чанки


  1. Перейдите в AI Factory → Managed RAG.

  2. Нажмите на карточку базы знаний api-chunks-kb.

  3. Перейдите на вкладку Чанки.

  4. В строке Контент нажмите на содержимое чанка с типом источника Custom.

Откроется информация о чанке.

5. Отправьте поисковый запрос

Managed RAG предоставляет пользователям доступ к Searh API. С его помощью можно отправлять к базе знаний запросы на поисковую выдачу для проверки релевантности ответов LLM-модели. В результате запроса API вернет список наиболее подходящих по контексту чанков с оценкой релевантности.

Выполните поисковый запрос:

curl -X POST 'https://<knowledgebase_id>.managed-rag.inference.cloud.ru/api/v2/retrieve \
-H "Content-Type: application/json" \
-H 'Authorization: Bearer <access_token> \
-d '{
"knowledge_base_version": "<knowledgebase_version_id>",
"query": "<query>",
"retrieval_configuration": {
"number_of_results": 3,
"retrieval_type": "SEMANTIC"
}
}'

Где:

  • <knowledgebase_id> — идентификатор базы знаний.

  • <access_token> — токен доступа, полученный перед началом работы.

  • <knowledgebase_version> — идентификатор версии базы знаний.

  • "number_of_results" — количество возвращаемых чанков в поисковой выдаче.

  • "retrieval_type" — тип поиска. В данном случае используется семантический поиск.

6. Отправьте поисковый запрос с фильтром

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

Выполните поисковый запрос:

curl -X POST 'https://<knowledgebase_id>.managed-rag.inference.cloud.ru/api/v2/retrieve \
-H "Content-Type: application/json" \
-H 'Authorization: Bearer <access_token> \
-d '{
"knowledge_base_version": "<knowledgebase_version_id>",
"query": "<query>",
"retrieval_configuration": {
"number_of_results": 3,
"retrieval_type": "SEMANTIC"
"filter": {
"metadata": {
"equals": {
"key": "datasource_type",
"value": "CUSTOM"
}
}
}
}
}'

Где:

  • <knowledgebase_id> — идентификатор базы знаний.

  • <access_token> — токен доступа, полученный перед началом работы.

  • <knowledgebase_version> — идентификатор версии базы знаний.

  • "number_of_results" — количество возвращаемых чанков в поисковой выдаче.

  • "retrieval_type" — тип поиска. В данном случае используется семантический поиск.

  • equals — объект с условием фильтрации. Состоит из:

    • key — ключ метаданных. В примере datasource_type — тип источника данных.

    • value — значение метаданных. В примере CUSTOM — источник данных API.

Результат

Вы научились:

  • создавать чанки в базе знаний с помощью API;

  • находить информацию о чанках;

  • отправлять поисковые запросы.