E-commerce Retail RAG + MCP Kundenservice-System

Ein Multi-Source-RAG-Kundenservice-System (Retrieval-Augmented Generation) für E-Commerce-/Einzelhandelsszenarien. Es orchestriert Agenten mit Google ADK, durchsucht den Produktkatalog sowie Rückgabe- und Versandrichtlinien und lässt das LLM nach der RRF-Multi-Source-Fusion (Reciprocal Rank Fusion) auf Basis von Kontext mit Quellenangaben zuverlässige Antworten generieren – ganz ohne Halluzinationen.

✨ Kernfunktionen

Related MCP server: ecommerce-catalog-agent

📊 Ergebnisse der Sekundärentwicklung (direkt in den Lebenslauf aufnehmbar)

RRF-Fusions-Vergleichsexperiment – Bei denselben 12 Abfragen wird der Recall-Effekt von „RRF-Fusion" und „direkter Verkettung" verglichen:

Fazit: Wenn der Produktkatalog (starke Quelle) ein weitaus größeres Volumen hat als die Richtlinien (schwache Quelle), werden die Richtliniendokumente bei direkter Verkettung vollständig überlagert; nach der RRF-Fusion steigen die relevanten Dokumente deutlich nach oben. Die vollständige Analyse finden Sie in docs/RRF对比实验报告.html.

Stolperfallen-Protokoll (Pluspunkte im Vorstellungsgespräch) → docs/RAG二开踩坑记录.html

🚀 Schnellstart — Demo live ausführen

Es wird nur lokales Ollama benötigt, keine Cloud-API-Keys. In 5 Minuten lauffähig.

# 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

Beispielfragen: do you refund damaged produce, free delivery over 35 dollars.

Die Suche der Demo basiert auf einem vorab berechneten Embedding-Cache embedding_index.json + embeddings_cache.npy (von Ollama generiert). Eine In-Memory-Cosinus-Suchschicht ist bereits integriert, sodass kein separater ChromaDB-Start erforderlich ist – das vermeidet die Fallstricke der lokalen Persistenz unter Windows.

🧪 Vergleichsexperiment reproduzieren

python scripts/compare_rrf_vs_join.py

💻 Technologie-Stack

• Orchestrierung: Google ADK (FunctionTool + SequentialAgent)

• Embedding/Generierung: Ollama (nomic-embed-text / qwen2.5:3b), rein lokal

• Vektor-Suche: Vorab berechneter Embedding-Cache + NumPy-In-Memory-Cosinus-Suche (ursprüngliche ChromaDB-Adapter-Schicht beibehalten)

• Fusions-Ranking: Eigenentwickeltes RRF (agents/tools/rrf_fusion.py)

• Service: FastAPI-MCP-Server (src/mcp_server)

📁 Verzeichnisstruktur

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/                         # 含嵌入一致性守卫测试

✅ Tests

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

🌱 Nächste Schritte

• Anbindung weiterer Suchquellen (Bewertungen, Lagerbestand) sowie eines Rerankers für das Neusortieren

• Erweiterung um eine Evaluierungs-Pipeline (recall@k / groundedness)

• RBAC / Ratenbegrenzung für MCP-Tools