# rag_agent

**Repository Path**: wangyuew/rag_agent

## Basic Information

- **Project Name**: rag_agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-22
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM Growth Project

一个面向广告投放与广告合规场景的 RAG + Agent 应用工程项目。

项目目标不是做一个只会调用模型的 demo，而是完整练习 LLM 应用从检索、工具调用、结构化输出、后处理、debug 到 eval 的工程链路。

## 核心能力

```text
RAG
-> 广告规则知识库问答
-> TF-IDF / embedding / hybrid 检索
-> evidence 回填
-> retrieval / answer eval

Campaign Agent
-> 广告投放诊断
-> 单轮诊断
-> 多轮追问
-> memory
-> deterministic followup
-> debug / eval

Tool Agent
-> planner
-> executor
-> tool trace
-> LLM shadow planner
-> guardrail / fallback

Unified Ask
-> 自然语言统一入口
-> 自动路由 RAG / Agent / mixed
-> campaign 名称解析
-> RAG + Agent 结果 merge
-> /ask/chat 多轮入口
```

## 架构概览

```text
用户问题
  |
  v
/ask or /ask/chat
  |
  v
orchestrator_router.py
  |
  +-- RAG route
  |     docs/policies/*.md
  |       -> document_loader
  |       -> vector store / embedding / hybrid
  |       -> /rag/answer
  |
  +-- Campaign Agent route
  |     campaign_resolver
  |       -> tool_planner
  |       -> tool_executor
  |       -> analyzer
  |       -> campaign diagnosis
  |
  +-- Mixed route
        RAG + Campaign Agent
          -> merge_unified_answers
          -> final_answer
```

## 目录说明

```text
gateway/app.py
  FastAPI 应用创建和路由注册入口。

gateway/routes/
  HTTP route 层，按 Core、RAG、Campaign Agent、Relevance、Unified Ask 等能力拆分 API。

gateway/common/
  配置、错误码、日志、JSON 解析、LLM client 等通用基础设施入口。

gateway/rag/
  RAG 文档加载、检索、embedding、hybrid scorer、RAG answer service。

gateway/campaign/
  Campaign Agent 的 tools、analyzer、planner、executor、memory、diagnosis service。

gateway/orchestrator/
  /ask 统一入口路由、campaign 解析、RAG + Agent 跨能力编排 service。

evals/
  RAG、Campaign Agent、Tool Agent、Unified Ask 的效果评测脚本。

tests/
  快速、确定性的工程测试脚本。

docs/
  阶段学习总结和设计文档。

data/
  policy chunks、embedding、campaign mock data、eval reports。
```

## 快速开始

```bash
cd /Users/guowanlong/code/llm-growth-project
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

安装 Ollama 模型：

```bash
ollama pull qwen2.5:3b
ollama pull nomic-embed-text
```

`.env` 示例：

```bash
LLM_PROVIDER=ollama
OPENAI_BASE_URL=http://127.0.0.1:11434/v1
OPENAI_API_KEY=ollama
OPENAI_MODEL=qwen2.5:3b

MODEL_RAG_QA=qwen2.5:3b
MODEL_CAMPAIGN_DIAGNOSIS=qwen2.5:3b
MODEL_QUERY_AD_RELEVANCE=qwen2.5:3b
MODEL_TOOL_PLANNER=qwen2.5:3b
MODEL_JSON_REPAIR=qwen2.5:3b

EMBEDDING_BASE_URL=http://127.0.0.1:11434/api/embed
EMBEDDING_MODEL=nomic-embed-text
EMBEDDING_CACHE_ENABLED=true

HYBRID_ALPHA=0.5
HYBRID_BETA=0.5
```

`LLM_PROVIDER` 支持：

```text
ollama
openai_compatible
mock
```

其中 `ollama` 和 `openai_compatible` 都走 OpenAI-compatible Chat Completions 协议，只是 base_url/model 配置不同；`mock` 用于本地工程测试和无模型环境的链路验证。

模型选择分两层：

```text
LLM_PROVIDER
  -> 决定调用哪个模型服务，例如 ollama/openai_compatible/mock

MODEL_*
  -> 决定不同业务场景使用哪个模型
```

模型路由优先级：

```text
接口显式传入 model
> MODEL_RAG_QA / MODEL_CAMPAIGN_DIAGNOSIS / MODEL_JSON_REPAIR 等业务配置
> scene_config.default_model
> OPENAI_MODEL
```

构建 RAG 数据：

```bash
python -m gateway.rag.document_loader
python -m gateway.rag.build_embeddings
```

启动服务：

```bash
uvicorn gateway.app:app --reload --port 8000
```

## 常用 API

### RAG 问答

```bash
curl -X POST http://127.0.0.1:8000/rag/answer \
  -H "Content-Type: application/json" \
  -d '{
    "question": "教育广告能不能写包过？",
    "top_k": 3,
    "retriever_type": "hybrid"
  }'
```

### Campaign 单轮诊断

```bash
curl -X POST http://127.0.0.1:8000/campaign/diagnose \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign_001",
    "question": "最近 7 天 CPA 为什么上涨？"
  }'
```

### Tool Agent 诊断

```bash
curl -X POST http://127.0.0.1:8000/campaign/tool-agent/diagnose \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign_001",
    "question": "哪些 query 可能拉高了 CPA？"
  }'
```

### 统一自然语言入口

```bash
curl -X POST http://127.0.0.1:8000/ask \
  -H "Content-Type: application/json" \
  -d '{
    "message": "少儿英语春季招生最近 CPA 涨了，创意里能不能写包过？"
  }'
```

### 统一入口多轮追问

```bash
curl -X POST http://127.0.0.1:8000/ask/chat \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "demo_session_001",
    "message": "少儿英语那个计划 CPA 怎么涨了？"
  }'

curl -X POST http://127.0.0.1:8000/ask/chat \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "demo_session_001",
    "message": "那先处理哪个 query？"
  }'
```

## Debug API

```text
/campaign/diagnose/debug
/campaign/chat/debug
/campaign/tool-agent/debug
/ask/debug
```

Debug 接口用于观察：

- router 结果
- campaign 识别结果
- tool plan
- tool trace
- raw LLM answer
- normalized answer
- merge result

## 一键演示

```bash
python -m gateway.demo
```

演示内容：

- RAG 广告规则问答
- Campaign Agent 单轮诊断
- Tool Agent trace
- Unified Ask mixed 调用
- Unified Ask Chat 多轮追问

## 回归评测

RAG：

```bash
python -m evals.rag.evaluate_retrieval
python -m evals.rag.evaluate_embedding_retrieval
python -m evals.rag.evaluate_hybrid_retrieval
python -m evals.rag.evaluate_answer tfidf
python -m evals.rag.evaluate_answer embedding
python -m evals.rag.evaluate_answer hybrid
python -m evals.rag.summarize_eval_reports
```

Campaign Agent：

```bash
python -m evals.campaign.evaluate_diagnosis
python -m evals.campaign.evaluate_chat
```

Tool Agent：

```bash
python -m evals.campaign.evaluate_tool_agent
python -m evals.campaign.evaluate_tool_trace
python -m evals.campaign.evaluate_llm_tool_planner
```

Unified Ask：

```bash
python -m evals.orchestrator.evaluate_campaign_resolver
python -m evals.orchestrator.evaluate_unified_ask
python -m evals.orchestrator.evaluate_unified_ask_debug
python -m evals.orchestrator.evaluate_unified_ask_chat
```

工程测试：

```bash
python -m tests.rag.test_engineering_guards
python -m tests.campaign.test_followup_intent
```

## 设计亮点

### 1. RAG 不是只召回文本

- 支持多 retriever：`tfidf`、`embedding`、`hybrid`
- hybrid scorer 融合 TF-IDF、embedding、业务 boost
- answer 必须返回 evidence chunk id
- 后处理会校验 evidence 是否真实存在

### 2. Agent 不只靠 Prompt

Campaign Agent 中，LLM 负责组织语言，但关键边界由服务端兜底：

- `pre_analysis` 生成确定性业务 insight
- root causes / evidences / suggestions 会被 normalize
- 健康 campaign 会被服务端纠偏
- raw answer 可以错，final answer 必须稳

### 3. Tool Agent 有 Trace

Tool Agent 不是一次性取全量数据，而是：

```text
planner -> executor -> analyzer -> answer
```

Debug 中可以看到：

- 计划调用哪些工具
- 实际执行哪些工具
- 每个工具输入、输出摘要、耗时和状态

### 4. LLM Planner 只做 Shadow

项目尝试了 LLM planner，但没有直接上线替换规则 planner。

原因是初始评测中 LLM planner 会出现：

- focus 非法
- 多选工具
- 倾向全量取数

因此增加了：

- focus whitelist
- tool whitelist
- tools_for_focus
- rule fallback
- shadow eval

### 5. RAG + Agent 统一编排

`/ask` 可以处理：

- 纯规则问题 -> RAG
- 纯投放问题 -> Agent
- 混合问题 -> RAG + Agent + merge

这更接近真实 AI 应用的入口形态。

## 当前限制

- campaign 数据仍是 mock JSON
- memory 仍是内存版，服务重启会丢
- router / resolver 主要是规则版
- mixed query decomposition 仍比较简单
- 没有权限控制
- 没有 Web UI
- 还没有 C++ client

## 推荐阅读

- `docs/rag_learning_summary.md`
- `docs/day_campaign_agent_stage_summary.md`
- `docs/day_campaign_tool_agent.md`
- `docs/day_unified_ask_orchestrator.md`
- `docs/day_campaign_chat_memory.md`
- `docs/day_campaign_002_agent_guardrails.md`