ваше сообщение коммита

2025-07-03 21:54:00 +03:00
parent 11cf0ea353
commit 972553dbb1
21 changed files with 1435 additions and 176 deletions
--- a/md/RAG_SEARCH_SETUP_AND_TEST.md
+++ b/md/RAG_SEARCH_SETUP_AND_TEST.md
@@ -1,35 +1,35 @@
 # План настройки и тестирования поиска по таблице RAG

 ## 1. Подготовка таблицы RAG
- Убедиться, что таблица RAG создана и содержит пары "вопрос-ответ".
- Добавить несколько тестовых записей через UI или напрямую в базу данных.
+- [x] Убедиться, что таблица RAG создана и содержит пары "вопрос-ответ".
+- [x] Добавить несколько тестовых записей через UI или напрямую в базу данных.

 ## 2. Настройка провайдера эмбеддингов
- В настройках ассистента выбрать нужного провайдера (OpenAI, Ollama и др.).
- Ввести API-ключ и Base URL (например, для OpenAI: https://api.openai.com/v1).
- Сохранить настройки.
+- [x] В настройках ассистента выбрать нужного провайдера (OpenAI, Ollama и др.).
+- [x] Ввести API-ключ и Base URL (например, для OpenAI: https://api.openai.com/v1).
+- [x] Сохранить настройки.

 ## 3. Проверка настроек ассистента
- Убедиться, что выбран актуальный ID таблицы RAG.
- Проверить выбранного провайдера эмбеддингов.
- Установить порог релевантности (например, 0.95).
+- [x] Убедиться, что выбран актуальный ID таблицы RAG.
+- [x] Проверить выбранного провайдера эмбеддингов.
+- [x] Установить порог релевантности (например, 0.95).

 ## 4. Проверка backend-логики
- Проверить, что в backend (например, в ragService.js) реализован поиск по RAG с использованием выбранного провайдера эмбеддингов.
- Убедиться, что используется актуальный ID таблицы и динамический выбор провайдера.
- Проверить возможность изменения порога релевантности.
+- [x] Проверить, что в backend (например, в ragService.js) реализован поиск по RAG с использованием выбранного провайдера эмбеддингов.
+- [x] Убедиться, что используется актуальный ID таблицы и динамический выбор провайдера.
+- [x] Проверить возможность изменения порога релевантности.

 ## 5. Тестирование через UI
- Отправить ассистенту вопрос, который есть в RAG-таблице — убедиться, что ответ возвращается из базы.
- Отправить вопрос, которого нет в таблице — убедиться, что ассистент либо не отвечает, либо использует LLM (по настройкам).
+- [ ] Отправить ассистенту вопрос, который есть в RAG-таблице — убедиться, что ответ возвращается из базы.
+- [ ] Отправить вопрос, которого нет в таблице — убедиться, что ассистент либо не отвечает, либо использует LLM (по настройкам).

 ## 6. Проверка логов backend
- Проверить логи на наличие сообщений о поиске по RAG, найденных совпадениях и выбранном провайдере эмбеддингов.
- В случае ошибок — проанализировать и устранить их.
+- [ ] Проверить логи на наличие сообщений о поиске по RAG, найденных совпадениях и выбранном провайдере эмбеддингов.
+- [ ] В случае ошибок — проанализировать и устранить их.

 ## 7. Тестирование через API (опционально)
- Использовать Postman/curl для отправки запросов напрямую к backend.
- Пример запроса:
+- [ ] Использовать Postman/curl для отправки запросов напрямую к backend.
+- [ ] Пример запроса:
  ```http
  POST /api/chat/message
  {
@@ -39,13 +39,32 @@
  ```

 ## 8. Автоматизация тестирования (по желанию)
- Написать автотесты (например, на Mocha/Jest), которые будут отправлять вопросы и сверять ответы с ожидаемыми из RAG.
+- [ ] Написать автотесты (например, на Mocha/Jest), которые будут отправлять вопросы и сверять ответы с ожидаемыми из RAG.

 ## 9. Рекомендации
- Для тестов использовать уникальные, простые вопросы и ответы.
- После каждого изменения настроек проводить тестовые запросы.
- Добавить в UI индикатор источника ответа (из базы или сгенерирован).
+- [ ] Для тестов использовать уникальные, простые вопросы и ответы.
+- [ ] После каждого изменения настроек проводить тестовые запросы.
+- [ ] Добавить в UI индикатор источника ответа (из базы или сгенерирован).

 ---

+## Этапы внедрения сервиса векторного поиска (под ключ)
+
+- [x] 1. Проектирование и создание структуры Python-сервиса (FastAPI + FAISS)
+- [x] 2. Реализация REST API: /upsert, /search, /delete, /rebuild, /health
+- [x] 3. Интеграция с Ollama для генерации эмбеддингов
+- [x] 4. Dockerfile и docker-compose для сервиса
+- [ ] 5. Интеграция Node.js backend с новым сервисом (HTTP-клиент)
+- [ ] 6. Перенос логики поиска из ragService.js на новый сервис
+- [ ] 7. Тестирование интеграции (ручное и через API)
+- [ ] 8. Документация по запуску и использованию
+- [ ] 9. Финальное тестирование через UI и API
+- [ ] 10. Передача проекта заказчику
+
+---
+
+**Прогресс:**
+- Сервис векторного поиска реализован, поддерживает кэширование, интеграцию с Ollama, все основные REST API.
+- Следующий этап — интеграция с Node.js backend и перенос логики поиска.
+
 **Если потребуется пример кода или помощь с конкретной реализацией — обращайтесь!** 
--- a/md/vector-search-service.md
+++ b/md/vector-search-service.md
@@ -0,0 +1,108 @@
+# Техническое задание: Векторный сервис поиска по таблице
+
+## Цель
+Реализовать отдельный микросервис для векторного поиска по данным из таблицы в базе данных. Сервис должен предоставлять REST API для добавления, поиска и обновления векторных представлений (эмбеддингов) строк таблицы.
+
+## Язык и стек
+- Язык: Python 3.10+
+- Векторный движок: FAISS
+- API: FastAPI
+- Хранение индекса: на диске (persistency)
+- Docker-образ для деплоя
+
+## API сервиса
+
+### 1. Добавление/обновление записей
+- **POST /upsert**
+- Тело запроса:
+  ```json
+  {
+    "table_id": "string",           // идентификатор таблицы
+    "rows": [
+      {
+        "row_id": "string",         // идентификатор строки
+        "text": "string",           // текст для эмбеддинга
+        "metadata": { ... }          // любые дополнительные поля
+      }
+    ]
+  }
+  ```
+- Ответ: `{ "success": true }`
+
+### 2. Поиск похожих записей
+- **POST /search**
+- Тело запроса:
+  ```json
+  {
+    "table_id": "string",
+    "query": "string",              // текст запроса
+    "top_k": 3                       // количество результатов
+  }
+  ```
+- Ответ:
+  ```json
+  {
+    "results": [
+      {
+        "row_id": "string",
+        "score": float,
+        "metadata": { ... }
+      }
+    ]
+  }
+  ```
+
+### 3. Удаление записей
+- **POST /delete**
+- Тело запроса:
+  ```json
+  {
+    "table_id": "string",
+    "row_ids": ["string", ...]
+  }
+  ```
+- Ответ: `{ "success": true }`
+
+### 4. Пересоздание индекса (опционально)
+- **POST /rebuild**
+- Тело запроса:
+  ```json
+  {
+    "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 (фрагмент)
+```yaml
+services:
+  vector-search:
+    build: ./vector-search
+    ports:
+      - "8001:8001"
+    environment:
+      - OLLAMA_BASE_URL=http://ollama:11434
+    depends_on:
+      - ollama
+```