# cs-agent

**Repository Path**: wanfangqing/cs-agent

## Basic Information

- **Project Name**: cs-agent
- **Description**: 客服agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能客服 Agent

基于 LangGraph + LlamaIndex 的生产级智能客服 Agent 系统。

## 架构概览

```
START → input_guard → context_loader → intent → slot_filling
      → route_decision
          ├→ sales (ReAct 子图)
          ├→ support (ReAct 子图)
          ├→ escalate (ReAct 子图)
          ├→ rag_retrieve (LlamaIndex RAG)
          └→ response
      → output_guard → closure
      → memory_update → context_loader (循环) → END
```

## 技术栈

| 组件 | 选型 |
|------|------|
| Agent 编排 | LangGraph 1.2+ |
| LLM 交互 | LangChain 1.x (langchain-core 1.5+) |
| RAG | LlamaIndex (VectorStoreIndex + BGE Reranker) |
| Web 框架 | FastAPI |
| 数据库 | MySQL 8.0+ (langgraph-checkpoint-mysql) |
| 缓存 | Redis 7.x |
| 向量库 | Chroma (开发) / Milvus (生产) |
| 可观测性 | LangSmith + OpenTelemetry + Prometheus |

## 核心功能

- **对话引擎**: 意图识别 + 情感分析 + 槽位填充 + 多轮对话管理
- **Multi-Agent**: Supervisor + ReAct 子图 (Sales/Support/Escalate)
- **RAG 知识检索**: LlamaIndex 混合检索 + BGE-Reranker 重排 + 引用溯源
- **MCP 工具**: 工具注册中心 + 沙箱执行 + 风险分级确认
- **安全护栏**: Prompt 注入检测 + PII 脱敏 + 输出审核
- **记忆系统**: 三层架构 (工作/短期/长期) + 遗忘策略
- **生产韧性**: 熔断器 + 限流 + 三级降级 + 语义缓存
- **评估体系**: 离线评估 + LLM-as-Judge 在线评估 + A/B 测试

## 快速开始

### 1. 安装

```bash
# 指定python版本安装虚拟环境.venv
py -3.11 -m venv .venv
.venv\Scripts\activate  # Windows
pip install -e ".[dev]"
```

### 2. 配置

```bash
cp .env.example .env
# 编辑 .env, 填入 OPENAI_API_KEY
```

### 3. 启动基础设施

```bash
docker compose up -d  # MySQL + Redis + Chroma
```

### 4. 摄入知识文档

```bash

# 1. 用 HF 镜像站下载模型到本地 (只需一次)
set HF_ENDPOINT=https://hf-mirror.com
# 需要获取token
hf download  BAAI/bge-m3 --local-dir models/bge-m3
hf download BAAI/bge-reranker-v2-m3 --local-dir models/bge-reranker-v2-m3

# 如果HF不行，则可以使用下载方式2 使用git
用 git clone 下载（通过 HF 镜像）：
# 确保 git lfs 已安装
git lfs install
# 下载 embedding 模型（~2.2GB）
git clone https://hf-mirror.com/BAAI/bge-m3 models/bge-m3
# 下载 reranker 模型（~1.1GB）
git clone https://hf-mirror.com/BAAI/bge-reranker-v2-m3 models/bge-reranker-v2-m3

# 以上都不行，则使用国内的服务，比如阿里百炼

# 2. 在 .env 中配置本地路径
EMBEDDING_LOCAL_PATH=models/bge-m3
RERANKER_LOCAL_PATH=models/bge-reranker-v2-m3

python scripts/ingest_docs.py --dir data/knowledge_base/

```

### 5. 启动服务

```bash
# 8000 端口已经被chroma占用了 
uvicorn cs_agent.api.app:app --host 0.0.0.0 --port 8001  --reload
#  单 worker 启动，方便断点调试
uvicorn cs_agent.api.app:app --host 0.0.0.0 --port 8001 --reload --workers 1
# 如果直接使用uvicorn启动不了，则使用python模块方式启动
python -m uvicorn cs_agent.api.app:app --host 0.0.0.0 --port 8001 --reload --workers 1
```

### 6. 测试对话

```bash
curl -X POST http://localhost:8001/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你们的退货政策是什么?", "session_id": "test-1"}'


# 如果访问404 检查端口是否被其它进程占用
netstat -ano | findstr :8001
# 杀掉旧进程
taskkill /F /PID 18028
# 重新启动服务
```

### 7. 运行测试

```bash
pytest tests/ -v  # 130+ tests
```

## 项目结构

```
src/cs_agent/
├── state/           # AgentState 状态定义
├── graph/           # LangGraph 状态图
│   └── subgraphs/   # Multi-Agent 子图 (sales/support/escalate)
├── nodes/           # 图节点 (意图/槽位/响应/安全/记忆)
├── edges/           # 条件路由边
├── memory/          # 三层记忆系统
├── rag/             # LlamaIndex RAG 管道
├── tools/           # MCP 工具系统， 查询订单，查询知识库
├── guardrails/      # 安全护栏 (输入/输出)
├── llm/             # LLM 网关 + 语义缓存
├── resilience/      # 生产韧性 (熔断/降级/限流)
├── api/             # FastAPI 接口 (REST + WebSocket)
├── observability/   # 可观测性 (LangSmith + Prometheus)
├── evaluation/      # 评估体系 (离线/在线/A-B)
└── config/          # 配置管理 + Prompt 模板
```

## 部署

### Docker Compose (生产)
```bash
docker compose -f docker-compose.prod.yml up -d
```

### Kubernetes
```bash
kubectl apply -f deploy/k8s/deployment.yaml
```

## 分阶段实施

| Phase | 内容 | 状态 |
|-------|------|------|
| 1 | 基础骨架 (状态图 + API + Checkpoint) | ✅ |
| 2 | 对话引擎 (意图/槽位/情感/上下文) | ✅ |
| 3 | 知识 & 工具 (LlamaIndex RAG + MCP) | ✅ |
| 4 | Multi-Agent (ReAct 子图 + 路由) | ✅ |
| 5 | 安全 & 记忆 & 韧性 | ✅ |
| 6 | 生产化 (监控/部署/评估) | ✅ |