02 · 项目总览与 5 分钟跑起来

一、这个项目到底干什么

一句话：让业务同事用大白话问数据和制度，Agent 自己去查、去算、去核对，最后给出带出处的答案；遇到危险动作会先停下来等人点头。

三个典型场景：

用户问	Agent 做什么	用到的能力
"P0 缺陷多久必须修复？"	检索《缺陷分级与处理规范》→ 组织答案 → 标注出处	RAG + 引用溯源
"本月各项目成本排名前 5？"	生成 SQL → 只读校验 → 查 BI 库 → 生成结论	Text2SQL + 护栏
"把超支 20% 的项目告警推到值班群"	查数据 → 中断 → 等人工点确认 → 推送	多步编排 + HITL

二、架构图

sql 复制代码

┌────────────────────────────────────────────────────────────┐
│  Vue3 工作台：对话流 / 执行链路时间线 / 引用溯源 / 确认卡片   │
└───────────────▲────────────────────────────────────────────┘
                │ SSE: token / plan / tool_start / tool_end
                │      / reflect / hitl / final / llm_usage
┌───────────────┴────────────────────────────────────────────┐
│  API 层  FastAPI（Python） / Spring Boot（Java）             │
└───────────────▲────────────────────────────────────────────┘
┌───────────────┴────────────────────────────────────────────┐
│  Agent 编排                                                  │
│   Plan ──▶ Execute ──▶ Reflect ──▶（不够则回到 Execute）     │
│                  │                                           │
│           ToolRegistry（Function Calling）                   │
└────────┬─────────┴──────────┬──────────────┬────────────────┘
         ▼                    ▼              ▼
    RAG 检索            BI 数据(SQL)     告警推送(HITL)
   向量 + BM25          只读校验          计算器 / 日期
   RRF + Rerank         报错回炉

横切：Guardrails · Memory(窗口+摘要) · Tracer(Span/Token) · LLM适配(重试+降级)

三、目录结构

bash 复制代码

enterprise-agent-platform/
├── run_all.bat          # 一键启动（后端+前端）
├── run_python.bat       # 只启动后端
├── run_web.bat          # 只启动前端
├── docker-compose.yml   # PG(pgvector) + Redis + API
├── server-python/
│   ├── .env             # 配置（已填好 DeepSeek）
│   ├── app/
│   │   ├── config.py            # 配置中心（自动加载 .env）
│   │   ├── llm/                 # LLM 适配 / Prompt 模板
│   │   ├── rag/                 # 切分 / embedding / 向量库 / 检索
│   │   ├── agent/               # 状态 / 编排 / 工具 / 护栏 / 记忆
│   │   ├── observability/       # Tracer
│   │   ├── api/routes.py        # SSE 对话等接口
│   │   └── main.py
│   ├── data/knowledge/          # 知识库（3 篇制度文档）
│   ├── scripts/init_bi_db.py    # 生成 BI 演示库
│   └── tests/                   # 11 个用例
├── server-java/                 # Spring Boot + LangChain4j
├── web/                         # Vue3 前端
├── docs/                        # 岗位对标 / 架构 / 简历 / 面试
└── blog/                        # 本系列

四、5 分钟跑起来

方式一：双击 `run_all.bat`（推荐）

会自动开两个窗口：

后端：http://localhost:8000/docs
前端：http://localhost:5173

方式二：手工

powershell 复制代码

# 后端
cd enterprise-agent-platform\server-python
$env:PYTHONPATH="$PWD"
python -m uvicorn app.main:app --port 8000

# 前端
cd ..\web
npm install && npm run dev

方式三：Docker

bash 复制代码

docker compose up -d --build

五、没有 API Key 也能跑（Mock 设计）

这是我最满意的一个设计。项目内置两个"离线兜底"：

1）MockLLM ------ 规则式假模型

python 复制代码

class MockLLM(BaseLLM):
    def _as_json(self, q):
        if any(h in q for h in ("成本", "缺陷", "排名", ...)):
            steps.append({"tool": "sql_query", "args": {...}})
        return json.dumps({"thought": ..., "steps": steps})

能根据问题关键词输出合法的 JSON 计划，让 Plan→Execute→Reflect 完整走通。

2）HashingEmbedder ------ 本地零依赖向量

python 复制代码

# 中文按单字 + 相邻双字(bigram)，英文按词
# 有符号哈希投影到 1024 维 + sublinear tf(1+log(tf)) + L2 归一化
h = md5(token); idx = h % dim; sign = ±1
vec[idx] += sign * (1 + log(tf))

质量不如真 embedding，但检索链路是真的：切分、入库、混合召回、RRF、重排、阈值兜底全部执行。

收益：面试现场断网、客户内网、CI 环境，都能演示完整链路。

六、接真实模型

编辑 server-python/.env：

ini 复制代码

LLM_PROVIDER=openai
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_API_KEY=sk-xxx
LLM_MODEL=deepseek-chat

因为是 OpenAI 兼容协议 ，Qwen / 通义 / Moonshot / vLLM / Ollama 只换 base_url 和 model，代码一行不用改。

小提示：DeepSeek 不提供 embedding 接口，所以 EMBED_PROVIDER 保持 hashing（本地向量）；如果你有 OpenAI / 通义的 Key，可以改成 openai 用真正的语义向量。

七、跑测试