API

Owned by Dennis Victorovich
Last updated: Oct 25, 2024
4 min read

 

API для переписки и управления сервисами AutoFAQ

API позволяет:

  • от имени пользователя вести переписку с сервисом AutoFAQ, включая переписку с ботом и операторами сервиса

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

  • управлять настройками сервиса

Swagger документация API

 

KB CRUD API для управления Базами Знаний /core-api/crud/

CRUD API служит для создания Баз Знаний, наполнения их документами и публикации (design-time).

Для удобства все PUT JSON вызовы работают как REST JSON PATCH - то есть можно передать только те поля, значения которых необходимо обновить (нет нужды передавать полное состояние)

Swagger документация

Жизненный цикл БЗ:

  • Создание. БЗ имеет имя, настройки языка, режима дообучения и apikey service_token для доступа к опубликованному сервису QNA.

  • Наполнение документами. Документ - это (вопрос, ответ, опционально формулировки вопроса, файловые атачи)

  • Публикация. Опубликованная БЗ предоставляет сервис ответов на вопросы (см QNA API ниже)

  • Редактирование контента, модерация и прием рекоммендаций документов и формулировок.

  • Удаление БЗ

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

Возможны 2 варианта аутентификации

  1. jwt cookie полученная при авторизации в UI на странице /login либо через API вызов /api/ext/v2/login

  2. user_token - строковый ключ пользователя (access token, apikey) можно узнать у администратора.

При использовании user_token может быть передан несколькими способами:

  1. Предпочтительный: Standard Basic Auth HTTP header - Authorization: Bearer {user_token}

  2. Альтернативный: Private HTTP header AUTOFAQ-User-Token: {user_token}

 

Коды ошибок

 

response http code - 400 response content type - json response json.error === 'invalid_excel' response json.message === "Неизвестный формат файла" Текст ошибки пользователю: "Некорректный XLS файл" response http code - 400 response content type - json response json.error === 'invalid_excel' response json.message === "Файл должен содержать обязательные колонки 'наименование','ответ' и 'вопрос 1'" Текст ошибки пользователю: "Файл должен содержать обязательные колонки 'наименование','ответ' и 'вопрос 1'" response http code - 400 response content type - json response json.error === 'similar_paraphrase' Текст ошибки пользователю: `Схожая формулировка "${json.similar_paraphrase}" (${json.similar_paraphrase_id}) уже существует в документе ${json.similar_document_id} БЗ ${json.similar_service_id}` response http code - 400 response content type - json response json.error === 'similar_document' Текст ошибки пользователю: `Схожий документ уже существует ${json.similar_document_id} в БЗ ${json.similar_service_id} (формулировка "${json.similar_paraphrase}" (${json.similar_paraphrase_id}))` response http code - 400 response content type - json response json.error === 'invalid_parameter' response json.message === "invalid snapshot format - not zipfile" Текст ошибки пользователю: "Неизвестный формат файла" response http code - 400 response content type - json response json.error === 'invalid_parameter' Текст ошибки пользователю: "Некорректный запрос API БЗ" response http code - 404 response content type - json response json.error === 'not_found' Текст ошибки пользователю: "Ресурс не найден" response http code - 403 response content type - json response json.error === 'forbidden' Текст ошибки пользователю: "Недостаточно прав для доступа: (`json.message`)" response http code - 413 response content type - pain text текст содержит "Request Entity Too Large" Текст ошибки пользователю: "Размер файла превышает максимально допустимое значение" (Превышен Лимит на уровне nginx-router) response http code - 500 response content type - json response json.message содержит текст "Request Entity Too Large" Текст ошибки пользователю: "Размер файла превышает максимально допустимое значение" (Превышен Лимит на уровне backend API БЗ) response http code - 403 response content type - json response json.error === 'services_quota_exceeded' Текст ошибки пользователю: `Превышена квота на количество БЗ` response http code - 403 response content type - json response json.error === 'documents_quota_exceeded' Текст ошибки пользователю: `Превышена квота на количество документов в БЗ` response http code - 403 response content type - json response json.error === 'paraphrases_quota_exceeded' Текст ошибки пользователю: `Превышена квота на количество формулировок в документах БЗ` response http code - 403 response content type - json response json.error === 'resource_quota_exceeded' Текст ошибки пользователю: `Превышена квота на ресурсы БЗ (${json.message})` response http code - 403 response content type - json response json.error === 'requests_quota_exceeded' Текст ошибки пользователю: `Превышена квота на частоту обращений в API БЗ (${json.message})` response http code - 500 response content type - json response json.error === 'internal_error' Текст ошибки пользователю: 'Внутренняя ошибка' (Unhandled exception at backend)

Пример ошибок при добавлении/обновлении документов и формулировок

HTTP 400
Response JSON schema:

{ "error": {"type": "string","enum": ["paraphrases_quota_exceeded", "similar_paraphrase", "similar_document"]}, "message": {"type": "string"}, "similar_service_id": {"type": "integer"}, "similar_document_id": {"type": "integer"}, "similar_paraphrase_id": {"type": "integer"}, "similar_paraphrase": {"type": "string"} }

  • error

    • similar_paraphrase - в этом документе уже существует похожая формулировка

    • similar_document - в другом документе уже существует похожая формулировка

    • paraphrases_quota_exceeded - превышено ограничение на количество формулировок в документе

  • similar_paraphrase_id - ID схожей/конфликтующей формулировки

  • similar_document_id - ID документа содержащего similar_paraphrase_id

  • similar_service_id - ID БЗ сожержащей документ с similar_paraphrase_id

  • message - текст ошибки на английском языке

  • similar_paraphrase - текст схожей/конфликтующей формулировки (из similar_service_id/similar_document_id/similar_paraphrase_id)

KB QNA API /core-api/query/

QNA API служит для запросов на классификацию в опубликованной базе знаний и отправке обратной связи для дообучения базы знаний (run-time).

API позволяет

  • отправить запрос на классификацию текста по одной базе знаний

  • отправить пакетный запрос на классификацию по нескольким базам знаний сразу

  • отправить информацию для дообучения базы знаний (расширению обучающей выборки существующих записей или созданию новых записей)

Swagger документация

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

Каждая опубликованная БЗ имеет собственный ключ доступа к QNA API - service_token - строковый ключ (access token, apikey)

Ключ service_token можно получить из UI на странице настроек БЗ либо из CRUD API запросом CRUD API GET /core-api/crud/api/v1/services/{service_id}

service_token передается в теле запроса вместе с запрашиваемой БЗ service_id:

curl -v -H "Content-Type: application/json" -XPOST https://chat.autofaq.ai/core-api/query/api/v1/query -d ' {"query": "привет, сколько стоит", "top_k": 3, "service_id": 107742, "service_token": "{service_token}"} '

Подробнее примеры использования см вызовы методов /query и /click во вложении в демо скипте test_winnie_pooh.py

Пример использования batch query API

Квоты

Квоты на количество запросов в одну БЗ

Максимальное число запросов в минуту: 1200

Максимальное число запросов в сутки: 1000000

Примеры

Тривиальный пример жизненного цикла см скрипт test_winnie_pooh.py во вложении выше на этой странице .

Пример добавления документа с формулировками: