DLE/docs/vector-search-service.md

Техническое задание: Векторный сервис поиска по таблице

Цель

Реализовать отдельный микросервис для векторного поиска по данным из таблицы в базе данных. Сервис должен предоставлять REST API для добавления, поиска и обновления векторных представлений (эмбеддингов) строк таблицы.

Язык и стек

• Язык: Python 3.10+
• Векторный движок: FAISS
• API: FastAPI
• Хранение индекса: на диске (persistency)
• Docker-образ для деплоя

API сервиса

1. Добавление/обновление записей

• POST /upsert
• Тело запроса:

  {
    "table_id": "string",           // идентификатор таблицы
    "rows": [
      {
        "row_id": "string",         // идентификатор строки
        "text": "string",           // текст для эмбеддинга
        "metadata": { ... }          // любые дополнительные поля
      }
    ]
  }
  

• Ответ: { "success": true }

2. Поиск похожих записей

• POST /search
• Тело запроса:

  {
    "table_id": "string",
    "query": "string",              // текст запроса
    "top_k": 3                       // количество результатов
  }
  

• Ответ:

  {
    "results": [
      {
        "row_id": "string",
        "score": float,
        "metadata": { ... }
      }
    ]
  }
  

3. Удаление записей

• POST /delete
• Тело запроса:

  {
    "table_id": "string",
    "row_ids": ["string", ...]
  }
  

• Ответ: { "success": true }

4. Пересоздание индекса (опционально)

• POST /rebuild
• Тело запроса:

  {
    "table_id": "string"
  }
  

• Ответ: { "success": true }

Требования к эмбеддингам

• Для генерации эмбеддингов сервис использует Ollama (через HTTP API, модель mxbai-embed-large или аналогичную).
• Эмбеддинги кэшируются локально для ускорения поиска.

Требования к интеграции

• Сервис не хранит бизнес-логику, только индексы и метаданные.
• Node.js backend обращается к сервису по HTTP (localhost или через docker-compose).
• Все операции атомарны, сервис устойчив к сбоям.

Безопасность

• Сервис доступен только во внутренней сети (docker-compose).
• Нет публичного доступа извне.

Мониторинг и логирование

• Логирование всех запросов и ошибок.
• Healthcheck endpoint: GET /health (ответ: { "status": "ok" })

Docker

• Сервис должен запускаться как отдельный контейнер.
• Все зависимости описаны в requirements.txt.

Пример docker-compose.yml (фрагмент)

services:
  vector-search:
    build: ./vector-search
    ports:
      - "8001:8001"
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
    depends_on:
      - ollama