E-commerce Retail RAG + MCP Customer Service System

A multi-source Retrieval-Augmented Generation (RAG) customer service system for e-commerce/retail scenarios. It orchestrates Agents via Google ADK, retrieves from the product catalog and return/shipping policies, and after RRF (Reciprocal Rank Fusion) multi-source fusion ranking, lets the LLM generate reliable answers based on context with citations, eliminating hallucinations.

✨ Core Capabilities

Related MCP server: ecommerce-catalog-agent

📊 Secondary Development Results (Ready for Your Resume)

RRF Fusion Comparison Experiment —— Same 12 queries, comparing recall effectiveness between "RRF fusion" and "direct concatenation":

Conclusion: When the product catalog (strong source) is far larger than the policy (weak source), direct concatenation causes policy documents to be completely overwhelmed; after RRF fusion, relevant documents rise significantly. Full analysis in docs/RRF对比实验报告.html.

Pitfall Records (interview bonus points) → docs/RAG二开踩坑记录.html

🚀 Quick Start —— Run the Demo On-site

Only requires local Ollama, no cloud API key needed. Runnable in 5 minutes.

# 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

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

The Demo's retrieval relies on precomputed embedding cache embedding_index.json + embeddings_cache.npy (generated by Ollama), with a built-in in-memory cosine retrieval layer, so no need to start ChromaDB separately, avoiding the pitfalls of standalone persistence on Windows.

🧪 Reproduce the Comparison Experiment

python scripts/compare_rrf_vs_join.py

💻 Tech Stack

• Orchestration: Google ADK (FunctionTool + SequentialAgent)

• Embedding/Generation: Ollama (nomic-embed-text / qwen2.5:3b), fully local

• Vector Retrieval: Precomputed embedding cache + NumPy in-memory cosine retrieval (original ChromaDB adapter layer retained)

• Fusion Ranking: Custom RRF (agents/tools/rrf_fusion.py)

• Service: FastAPI MCP server (src/mcp_server)

📁 Directory Structure

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

✅ Testing

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

🌱 Future Directions

• Integrate more retrieval sources (reviews, inventory) and a Reranker

• Add evaluation pipeline (recall@k / groundedness)

• RBAC / rate limiting for MCP tools