API внешней базы знаний

На этой странице описан контракт API, который ваш внешний сервис знаний должен реализовать, чтобы Интеллос мог получать из него контент. Когда ваш API готов, см. Подключение внешней базы знаний для его регистрации в Интеллос.

Аутентификация

Интеллос отправляет настроенный вами API Key как Bearer-токен в каждом запросе:

Authorization: Bearer {API_KEY}

Логику аутентификации вы определяете на своей стороне. Интеллос только передаёт ключ — он его не проверяет.

Запрос

POST {your-endpoint}/retrieval
Content-Type: application/json
Authorization: Bearer {API_KEY}

Интеллос добавляет /retrieval к настроенному вами URL эндпоинта. Если вы зарегистрировали https://your-service.com, Интеллос отправляет запросы на https://your-service.com/retrieval.

Тело

Свойство	Обязательно	Тип	Описание
`knowledge_id`	Да	string	Идентификатор источника знаний в вашей внешней системе. Это значение, которое вы ввели в поле Внешний идентификатор базы знаний при подключении. Используйте его для маршрутизации запросов к нужному источнику знаний.
`query`	Да	string	Поисковый запрос пользователя.
`retrieval_setting`	Да	object	Параметры поиска. См. ниже.
`metadata_condition`	Нет	object	Условия фильтрации по метаданным. См. ниже.

`retrieval_setting`

Свойство	Обязательно	Тип	Описание
`top_k`	Да	int	Максимальное число возвращаемых результатов.
`score_threshold`	Да	float	Минимальная оценка сходства (0–1). Когда порог оценки в Интеллос отключён, это значение равно `0.0`.

`metadata_condition`

Интеллос передаёт условия по метаданным в ваш API, но в настоящее время не предоставляет пользователю интерфейс для их настройки. Этот параметр доступен только для программного использования.

Свойство	Обязательно	Тип	Описание
`logical_operator`	Нет	string	`and` или `or`. По умолчанию: `and`.
`conditions`	Да	array[object]	Список условий фильтрации.

Каждый объект в conditions:

Свойство	Обязательно	Тип	Описание
`name`	Да	string	Имя поля метаданных, по которому выполняется фильтрация.
`comparison_operator`	Да	string	Оператор сравнения. См. поддерживаемые значения ниже.
`value`	Нет	string, number или array[string]	Значение для сравнения. Опустите при использовании `empty` или `not empty`.

Поддерживаемые операторы сравнения

Оператор	Описание
`contains`	Содержит значение
`not contains`	Не содержит значение
`start with`	Начинается со значения
`end with`	Заканчивается значением
`is`	Равно значению
`is not`	Не равно значению
`in`	Соответствует любому значению из списка
`not in`	Не соответствует ни одному значению из списка
`empty`	Пусто
`not empty`	Не пусто
`=`	Равно (числовое)
`≠`	Не равно (числовое)
`>`	Больше
`<`	Меньше
`≥`	Больше или равно
`≤`	Меньше или равно
`before`	Раньше даты
`after`	Позже даты

Пример запроса

{
    "knowledge_id": "your-knowledge-id",
    "query": "What is Intellos?",
    "retrieval_setting": {
        "top_k": 3,
        "score_threshold": 0.5
    }
}

Ответ

Верните HTTP 200 с телом в формате JSON, содержащим массив records. Если ни один результат не соответствует запросу, верните пустой массив: {"records": []}.

`records`

Свойство	Тип	Описание
`content`	string	Найденный текстовый чанк. Интеллос использует его как контекст, передаваемый в LLM.
`score`	float	Оценка сходства (0–1). Используется для фильтрации по порогу оценки и ранжирования результатов.
`title`	string	Заголовок исходного документа.
`metadata`	object	Произвольные пары «ключ-значение», сохраняемые Интеллос.

Интеллос не отклоняет записи с отсутствующими полями, но пропуск content или score приведёт к неполным или неранжированным результатам.

Если вы включаете metadata в запись, оно должно быть объектом ({}), а не null. Значение metadata, равное null, вызывает ошибки в конвейере поиска Интеллос.

Пример ответа

{
    "records": [
        {
            "content": "This is the document for external knowledge.",
            "score": 0.98,
            "title": "knowledge.txt",
            "metadata": {
                "path": "s3://dify/knowledge.txt",
                "description": "dify knowledge document"
            }
        },
        {
            "content": "The Innovation Engine for GenAI Applications",
            "score": 0.66,
            "title": "introduce.txt",
            "metadata": {}
        }
    ]
}

Обработка ошибок

Интеллос проверяет HTTP-код состояния вашего ответа. Любой статус, отличный от 200, вызывает ошибку, которая отображается пользователю. По желанию вы можете вернуть структурированную информацию об ошибке в формате JSON:

Свойство	Тип	Описание
`error_code`	int	Код ошибки уровня приложения, который вы определяете сами.
`error_msg`	string	Понятное человеку описание ошибки.

Ниже приведены рекомендуемые коды ошибок. Это соглашения, а не требования, навязываемые Интеллос:

Код	Рекомендуемое использование
1001	Неверный формат заголовка Authorization
1002	Ошибка авторизации
2001	База знаний не найдена

Пример ответа с ошибкой

{
    "error_code": 1002,
    "error_msg": "Authorization failed. Please check your API key."
}

Начало работы

Создание

Публикация

Мониторинг

База знаний

Рабочее пространство

Руководства

API внешней базы знаний

Аутентификация

Запрос

Тело

`retrieval_setting`

`metadata_condition`

Пример запроса

Ответ

`records`

Пример ответа

Обработка ошибок

Пример ответа с ошибкой

​Аутентификация

​Запрос

​Тело

​retrieval_setting

​metadata_condition

​Пример запроса

​Ответ

​records

​Пример ответа

​Обработка ошибок

​Пример ответа с ошибкой

Аутентификация

Запрос

Тело

`retrieval_setting`

`metadata_condition`

Пример запроса

Ответ

`records`

Пример ответа

Обработка ошибок

Пример ответа с ошибкой