E-commerce Retail RAG + MCP カスタマーサポートシステム

EC・小売シナリオ向けのマルチソース検索拡張生成（RAG）カスタマーサポートシステム。Google ADK で Agent をオーケストレーションし、商品カタログと返品・配送ポリシーを検索し、RRF（Reciprocal Rank Fusion）マルチソースフュージョンでランキングした後、LLM に出典付きコンテキストに基づいて信頼性の高い回答を生成させ、幻覚を防止します。

✨ コア機能

Related MCP server: ecommerce-catalog-agent

📊 二次開発の成果（そのまま履歴書に記載可能）

RRFフュージョン比較実験 — 同じ12クエリで「RRFフュージョン」と「直接連結」のリコール効果を比較：

結論：商品カタログ（強いソース）のボリュームがポリシー（弱いソース）よりはるかに大きい場合、直接連結ではポリシードキュメントが完全に埋没します。RRFフュージョン後は関連ドキュメントが顕著に浮上します。完全な分析は docs/RRF对比实验报告.html を参照してください。

ハマりどころ記録（面接アピールポイント）→ docs/RAG二开踩坑记录.html

🚀 クイックスタート — その場でDemoを実行

ローカルの 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 とお試しください。

Demoの検索は、事前計算済みの埋め込みキャッシュ 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   # 静态检查

🌱 今後の方向性

• より多くの検索ソース（レビュー、在庫）とリランカー（Reranker）の統合

• 評価パイプラインの追加（recall@k / groundedness）

• MCPツールのRBAC / レート制限