ecommerce-retail-rag-mcp

{"type": "text"}# E-commerce Retail RAG + MCP система поддержки клиентов

Система поддержки клиентов на основе мультиисточниковой генерации с дополненной выдачей (RAG) для сценариев электронной коммерции/розничной торговли. Оркестрация агентов на базе Google ADK, поиск по каталогу товаров и политике возврата/доставки, а после ранжирования с помощью многоисточникового слияния RRF (Reciprocal Rank Fusion) LLM генерирует надежные ответы на основе контекста с указанием источников, исключая галлюцинации.

✨ Ключевые возможности

Related MCP server: ecommerce-catalog-agent

📊 Результаты доработки (можно сразу в резюме)

Сравнительный эксперимент RRF-слияния — на одинаковых 12 запросах сравнивается качество извлечения при «RRF-слиянии» и «прямой конкатенации»:

Вывод: когда объём каталога товаров (сильный источник) значительно превышает политику (слабый источник), прямая конкатенация полностью поглощает документы политики; после RRF-слияния релевантные документы заметно поднимаются. Полный анализ см. в docs/RRF对比实验报告.html.

Записи о граблях (плюс на собеседовании) → docs/RAG二开踩坑记录.html

🚀 Быстрый старт — запуск демо на месте

Нужен только локальный Ollama, облачный API-ключ не требуется. Запуск за 5 минут.

# 1. 启动 Ollama 并拉取所需模型（首次）
ollama serve &
ollama pull nomic-embed-text      # 嵌入模型（768维）
ollama pull qwen2.5:3b            # 生成模型

# 2. 安装 Python 依赖
pip install -r requirements.txt

# 3.（可选）如预计算嵌入缓存缺失则重建向量库
python scripts/_precompute_embeddings.py

# 4. 启动端到端 Web Demo
python scripts/demo_web.py
# 浏览器打开 http://127.0.0.1:8080

Попробуйте: do you refund damaged produce, free delivery over 35 dollars.

Поиск в демо зависит от предварительно вычисленного кэша эмбеддингов embedding_index.json + embeddings_cache.npy (сгенерирован Ollama), встроен слой косинусного поиска в памяти, не требуется отдельный запуск ChromaDB, что позволяет избежать проблем с персистентностью на Windows.

🧪 Воспроизведение сравнительного эксперимента

python scripts/compare_rrf_vs_join.py

💻 Технологический стек

• Оркестрация: Google ADK (FunctionTool + SequentialAgent)

• Эмбеддинги/генерация: Ollama (nomic-embed-text / qwen2.5:3b), полностью локально

• Векторный поиск: предварительно вычисленный кэш эмбеддингов + косинусный поиск в памяти на NumPy (адаптер ChromaDB сохранён)

• Слияние и ранжирование: собственная реализация RRF (agents/tools/rrf_fusion.py)

• Сервис: FastAPI MCP server (src/mcp_server)

📁 Структура каталога

scripts/
  demo_web.py                  # 端到端 Web Demo（问→检→带出处答）
  compare_rrf_vs_join.py       # RRF vs 直接拼接对比实验
  _precompute_embeddings.py    # 预计算嵌入缓存
  chat_rag_demo.py             # 命令行 RAG Demo
src/
  embeddings/ollama_client.py  # embed_text + generate_answer
  rag/
    inmemory_cache.py          # 内存余弦检索层（二开新增）
    vector_store.py            # ChromaDB 适配层（保留）
agents/
  tools/rrf_fusion.py          # RRF 融合算法（二开新增）
  rag_agent.py                 # ADK RAG Agent
  workflows.py                 # ADK 工作流
docs/
  RRF对比实验报告.html          # 二开：对比实验报告
  RAG二开踩坑记录.html          # 二开：踩坑技术博客
configs/                       # 环境变量模板
tests/                         # 含嵌入一致性守卫测试

✅ Тестирование

pytest tests/            # 单元测试 + 嵌入一致性守卫
bash scripts/checks.sh   # 静态检查

🌱 Дальнейшие направления

• Подключение дополнительных источников поиска (отзывы, остатки) и реранкеров

• Добавление конвейера оценки (recall@k / groundedness)

• RBAC / ограничение частоты запросов для MCP-инструментов