# agent_RABC

**Repository Path**: bighandsomeboy/agent_-rabc

## Basic Information

- **Project Name**: agent_RABC
- **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-10-01
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🏢 华为新员工培训助手（Onboarding Agent）

> 完全离线、权限感知、RAG+Agent 架构的企业新人培训助手。

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![LangGraph](https://img.shields.io/badge/LangGraph-1.1.x-green.svg)](https://langchain-ai.github.io/langgraph/)
[![ChromaDB](https://img.shields.io/badge/ChromaDB-0.6+-orange.svg)](https://www.trychroma.com/)
[![Ollama](https://img.shields.io/badge/Ollama-Qwen2.5--7B-purple.svg)](https://ollama.ai/)

---

## 📋 目录

- [快速开始](#快速开始)
- [架构概览](#架构概览)
- [项目结构](#项目结构)
- [功能特性](#功能特性)
- [API 文档](#api-文档)
- [测试](#测试)
- [部署](#部署)
- [FAQ](#faq)

---

## 🚀 快速开始

### 环境要求

| 组件 | 版本 | 说明 |
|------|------|------|
| Python | 3.10+ | 推荐 3.11+ |
| Ollama | latest | 需提前拉取 `qwen2.5:7b-instruct-q4_K_M` |
| CUDA | 12.1+ | 可选，CPU 亦可运行（较慢） |
| 内存 | 16GB+ | 嵌入模型 ~400MB + LLM ~4.5GB |
| 显存 | 8GB+ | GPU 推理推荐，CPU 模式不需要 |

### 一键启动

```bash
# 1. 克隆/进入项目目录
cd /path/to/onboarding-agent

# 2. 安装依赖（国内源加速）
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 3. 确保 Ollama 已运行并拉取模型
ollama pull qwen2.5:7b-instruct-q4_K_M

# 4. 构建知识库索引
python knowledge/build_index.py

# 5. 启动 Web UI
python ui/gradio_app.py

# 或使用一键启动脚本
bash run.sh
```

访问 **http://localhost:7860** 即可使用。

---

## 🏗️ 架构概览

```
┌─────────────────────────────────────────────────┐
│                   Gradio UI                      │
│         (角色选择 + 文本输入 + 图片上传)           │
└─────────────────┬───────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────┐
│                LangGraph Agent                   │
│                                                  │
│  Intent ──▶ Auth ──▶ RAG ──▶ Generate ──▶ Reflect │
│  (意图)    (权限)   (检索)   (生成)      (质检)    │
└──────┬──────────────┬───────────────────────────┘
       │              │
       ▼              ▼
┌──────────────┐ ┌──────────────┐
│  Ollama LLM  │ │  ChromaDB    │
│  (Qwen2.5)   │ │  (+ BGE)     │
└──────────────┘ └──────────────┘
```

### 数据流

| 步骤 | 节点 | 输入 | 输出 |
|------|------|------|------|
| 1 | Intent | query | intent 类别 |
| 2 | Auth | user_role | allowed_chunk_ids |
| 3 | RAG | query + filter | retrieved_docs |
| 4 | Generate | docs + role | answer |
| 5 | Reflect | answer + confidence | 降级/通过 |

---

## 📁 项目结构

```
onboarding-agent/
├── main.py                  # 程序入口（CLI + API）
├── config/
│   ├── settings.py          # 全局配置（Pydantic）
│   ├── roles.json           # RBAC 三级权限
│   └── prompts.yaml         # Prompt 模板
├── agent/
│   ├── workflow.py           # LangGraph 状态机
│   ├── state.py              # AgentState TypedDict
│   └── nodes/
│       ├── intent_node.py    # 意图分类
│       ├── auth_node.py      # 权限校验
│       ├── rag_node.py       # 向量检索
│       ├── generate_node.py  # 答案生成
│       └── reflect_node.py   # 质量自检
├── utils/
│   ├── rag_retriever.py      # ChromaDB 封装
│   ├── permission.py         # RBAC 管理
│   ├── multimodal.py         # 图像 OCR
│   └── logger.py             # 结构化日志
├── knowledge/
│   ├── raw/                  # 10 条 JSON 知识文档
│   ├── build_index.py        # 向量化入库
│   └── chroma_db/            # 持久化向量库
├── ui/
│   └── gradio_app.py         # Web 交互界面
├── tests/
│   ├── test_workflow.py      # 端到端测试
│   ├── test_rag.py           # 检索评估
│   └── data_mock/            # 测试数据
├── Dockerfile
├── docker-compose.yml
├── run.sh
├── requirements.txt
└── README.md
```

---

## ✨ 功能特性

### RBAC 权限感知

| 角色 | 可见文档 | 不可见 |
|------|---------|--------|
| 实习生 | 7 条（文化、入职、IT、安全、紧急） | 财务、薪酬、职业发展 |
| 员工 | 10 条（全部） | - |
| 经理 | 10 条（全部） | - |

### 多模态支持

- 📷 **截图提问**：上传截图 → PaddleOCR 提取文字 → 追加到检索查询
- 🖼️ **图像理解**：Florence-2 生成描述（可选）
- 🛡️ **优雅降级**：任何组件失败不影响主流程

### 回答格式

```
✅ 核心答案（分点列出）
📌 建议下一步（来自知识库 next_action）
⚠️ 注意事项（权限/合规提示）
```

---

## 📡 API 文档

### Python API

```python
from agent.workflow import run_agent

result = run_agent(
    user_role="intern",
    query="实习生第一周做什么？",
    image_path=None,  # 可选：截图路径
)

# result:
# {
#     "answer": "实习生在入职第一周需要...",
#     "confidence": 0.85,
#     "sources": ["doc_002_onboarding: 实习生入职第一周任务清单"],
#     "next_action": "联系导师安排第一次沟通...",
#     "intent": "query_onboarding",
#     "role_checked": True,
# }
```

### HTTP API（FastAPI，需登录）

```bash
# 启动 API 模式（信任边界 = 服务端身份认证，见 技术规格说明书 §5.7）
python main.py --api

# 1) 登录拿 token（服务端校验密码 + 回查 DB 取权威角色）
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "zhangsan", "password": "你的口令"}'
#   → {"access_token": "...", "principal": {...}}

# 2) 携带 Bearer token 调对话（角色以服务端回查为准，请求体身份字段不可信）
curl -X POST http://localhost:8080/api/v1/chat \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "第一周任务"}'

# 健康检查（免认证）
curl http://localhost:8080/api/v1/health
```

### CLI 模式

```bash
# 交互模式
python main.py

# 单次查询
python main.py --role intern --query "实习生第一周做什么？"

# 指定角色
python main.py --role employee --query "报销流程"
```

---

## 🧪 测试

```bash
# 运行全部测试
pytest tests/ -v

# 单独运行
python tests/test_rag.py
python tests/test_workflow.py

# 预期指标
# - 单元测试通过率: 100%
# - 检索命中率: >80%
# - 端到端延迟: <10s（不含 LLM）
```

---

## 🐳 部署

### Docker Compose（推荐）

```bash
# 启动完整服务（Ollama + Agent）
docker-compose up -d

# 首次需拉取模型
docker exec onboarding-ollama ollama pull qwen2.5:7b-instruct-q4_K_M

# 查看日志
docker-compose logs -f app

# 停止
docker-compose down
```

### Docker 单容器

```bash
docker build -t onboarding-agent .
docker run --gpus all -p 7860:7860 \
  -e ONBOARDING_LLM_BASE_URL=http://host.docker.internal:11434 \
  onboarding-agent
```

---

## ❓ FAQ

**Q: Ollama 连接失败（502）？**
A: 设置环境变量 `NO_PROXY="localhost,127.0.0.1"` 或在 Docker 内使用 `host.docker.internal`。

**Q: 8GB 显存不够？**
A: 使用 `Q4_K_M` 量化模型（~4.5GB），嵌入模型用 CPU（~400MB），推理后自动调用 `torch.cuda.empty_cache()`。

**Q: 如何添加新的知识文档？**
A: 在 `knowledge/raw/` 下添加 JSON 文件（参考现有格式），然后运行 `python knowledge/build_index.py --clear`。

**Q: 如何修改权限？**
A: 编辑 `config/roles.json`，调整 `allowed_categories` 和 `denied_chunks`，无需重启服务。

**Q: 支持哪些图片格式？**
A: PNG、JPG、BMP，通过 PaddleOCR 提取中文文字。OCR 失败自动降级。

---

## 📄 技术栈

| 组件 | 版本 |
|------|------|
| Python | 3.10+ |
| LangChain | 1.2.x |
| LangGraph | 1.1.x |
| ChromaDB | 0.6+ |
| Ollama | Qwen2.5-7B |
| BGE Embedding | small-zh-v1.5 |
| Gradio | 4.x |
| PyTorch | 2.2+ |
| Florence-2 | base (可选) |
| PaddleOCR | latest (可选) |

---

*Made with ❤️ for Huawei New Onboarding Experience*