E-commerce Retail RAG + MCP: Sistema de atención al cliente

Un sistema de generación aumentada por recuperación (RAG) de múltiples fuentes para escenarios de e-commerce/retail. Usa Google ADK para orquestar el agente, recupera el catálogo de productos y las políticas de devolución/entrega y, tras el ranqueo por fusión de múltiples fuentes (RRF, Reciprocal Rank Fusion), consigue que el LLM genere respuestas fiables basadas en contexto con fuentes, eliminando las alucinaciones.

✨ Capacidades principales

Related MCP server: ecommerce-catalog-agent

📊 Resultados del desarrollo (para añadir directamente al currículum)

Experimento de comparación de la fusión RRF — con las mismas 12 consultas, se compara el efecto de recuperación entre la fusión RRF y la concatenación directa:

Conclusión: cuando el catálogo de productos (fuente fuerte) supera ampliamente en volumen a las políticas (fuente débil), la concatenación directa hace que los documentos de políticas queden totalmente relegados; tras la fusión RRF, los documentos relevantes ascienden de forma notable. Análisis completo en docs/RRF对比实验报告.html

Registro de tropiezos (punto a favor en la entrevista) → docs/RAG二开踩坑记录.html

🚀 Comienzo rápido — Demo en funcionamiento

Solo necesitas Ollama a nivel local; no hace falta API Key en la nube. Puedes ejecutarlo en 5 minutos.

# 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

Prueba con preguntas como: do you refund damaged produce, free delivery over 35 dollars.

La recuperación del Demo está basada en la caché de embeddings precalculados embedding_index.json + embeddings_cache.npy (generada por Ollama). Ya incluye una capa de búsqueda por coseno en memoria, por lo que no hay que lanzar ChromaDB, evitando las malas pasadas de la persistencia local en Windows.

🧪 Reproducción del experimento comparativo

python scripts/compare_rrf_vs_join.py

💻 Pila tecnológica

• Orquestación: Google ADK (FunctionTool + SequentialAgent)

• Embeddings / generación: Ollama (nomic-embed-text / qwen2.5:3b), 100 % local

• Recuperación vectorial: embeddings precalculados + búsqueda por coseno en memoria con NumPy (se conserva la capa de adaptación original de ChromaDB)

• Fusión y ranqueo: RRF propio (agents/tools/rrf_fusion.py)

• Servicio: servidor FastAPI MCP (src/mcp_server)

📁 Estructura del proyecto

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

✅ Pruebas

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

🌱 Próximas etapas

• Integrar más fuentes de recuperación (comentarios, inventario) y un Reranker

• Añadir un pipeline de evaluación (recopy@k / fundamentación)

• RBAC / control de frecuencia en las herramientas MCP