API ИИ Агентов

API для прямого взаимодействия с ИИ агентами (классификация и извлечение данных).

примечание

Эти endpoints требуют JWT аутентификации. См. Аутентификация.

Классификация документа

Определение типа документа по тексту OCR.

Endpoint

POST /ai_agents/api/v1/classify/

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

Требуется JWT токен

Параметры

Параметр	Тип	Описание
ocr_draft	string	Текст документа после OCR

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

curl -X POST http://localhost:8000/ai_agents/api/v1/classify/ \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ocr_draft": "Invoice #12345\nDate: 2024-01-15\nBill To: ACME Corp\nAmount Due: $1,500.00"
  }'

Успешный ответ (200 OK)

{
  "data": {
    "outputs": {
      "text": "{\"type\": \"Invoice\", \"confidence\": 0.95}"
    }
  }
}

Ошибки

400 Bad Request - отсутствует ocr_draft:

{
  "error": "ocr_draft is required"
}

500 Internal Server Error - агент не настроен:

{
  "error": "AiAgentSettings is not configured"
}

---

Извлечение структурированных данных

Извлечение полей из текста документа.

Endpoint

POST /ai_agents/api/v1/extract/

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

Требуется JWT токен

Параметры

Параметр	Тип	Описание
ocr_draft	string	Текст документа после OCR

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

curl -X POST http://localhost:8000/ai_agents/api/v1/extract/ \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ocr_draft": "Invoice #12345\nDate: 2024-01-15\nBill To: ACME Corp\nAmount Due: $1,500.00"
  }'

Успешный ответ (200 OK)

{
  "data": {
    "outputs": {
      "text": "{\"invoice_number\": \"12345\", \"date\": \"2024-01-15\", \"amount\": \"1500.00\", \"vendor_name\": \"ACME Corp\"}"
    }
  }
}

---

Провайдеры ИИ

DocAI поддерживает два провайдера ИИ:

Dify

Dify - платформа для создания AI приложений.

Настройка:

1. Создайте Workflow приложение в Dify
2. Добавьте приложение в Admin → AI Agents → Dify приложения
3. Выберите приложение в настройках агента

Формат workflow:

• Вход: { "text": "OCR текст" }
• Выход: { "text": "JSON результат" }

n8n

n8n - платформа автоматизации с webhook endpoints.

Настройка:

1. Создайте Webhook workflow в n8n
2. Добавьте приложение в Admin → AI Agents → n8n приложения
3. Выберите приложение в настройках агента

---

Настройка в Admin

1. Создание приложения

Admin → AI Agents → Dify/n8n приложения → Add

Поле	Описание
Name	Название приложения
Token	API токен приложения

2. Настройка агента

Admin → AI Agents → Настройки ИИ Агента → Add

Поле	Описание
Provider	dify или n8n
IP / Domain	Адрес сервера ИИ
Classification App	Приложение для классификации
Extraction App	Приложение для извлечения

---

Примеры использования

Python

import requests

# Получение токена
token_response = requests.post(
    "http://localhost:8000/api/token/",
    json={"email": "user@example.com", "password": "password"}
)
access_token = token_response.json()["access"]

# Классификация
headers = {"Authorization": f"Bearer {access_token}"}
ocr_text = """
Invoice #INV-2024-001
Date: January 15, 2024
Bill To: ACME Corporation
Amount Due: $1,500.00
"""

response = requests.post(
    "http://localhost:8000/ai_agents/api/v1/classify/",
    headers=headers,
    json={"ocr_draft": ocr_text}
)

print(response.json())
# {"data": {"outputs": {"text": "{\"type\": \"Invoice\"}"}}}

JavaScript

async function classifyDocument(accessToken, ocrText) {
  const response = await fetch(
    "http://localhost:8000/ai_agents/api/v1/classify/",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${accessToken}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ ocr_draft: ocrText })
    }
  );

  return response.json();
}

---

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

Timeout

Запросы к ИИ агентам могут занимать длительное время. Таймаут по умолчанию: 900 секунд (15 минут).

Retry логика

При ошибках сети запросы автоматически повторяются (max 3 попытки).

Логирование

Все запросы к ИИ агентам логируются:

DEBUG [app_ai_agents.dify_client] === DIFY REQUEST ===
DEBUG [app_ai_agents.dify_client] URL: http://dify.example.com/v1/workflows/run
DEBUG [app_ai_agents.dify_client] === DIFY RESPONSE ===
DEBUG [app_ai_agents.dify_client] STATUS: 200