Day 1：需求来了：公司想做一个 AI 知识工单助手
Day 1：需求来了：公司想做一个 AI 知识工单助手
这是这个专栏的第一篇，接下来会花二十天时间，把一个企业级 AI 知识工单助手从零做起来，前端页面、后端接口、Agent 能力、部署上线全都会覆盖到，而不是只写一套后端接口。第一周的目标是不深究框架原理，先花五天把一个可访问、能对话的 AI 助手页面跑起来，今天要做的是最开始的那一步，把需求拆清楚，把系统架构画出来，再把前后端的项目骨架搭起来。
一、拆需求
需求是从客服团队那边过来的。公司每天要处理大量重复的工单，用户问的无非是订单状态、退款政策、物流进度这几类问题，客服人员大部分时间都花在翻聊天记录、查订单系统、对照售后政策文档上，真正需要人工判断的问题反而没多少。业务方的想法很直接，能不能做一个 AI 助手，先把这些重复问题接住，答不上来或者遇到高风险操作再转人工。这个想法听起来简单，但真要落地成一个能在公司内部用起来的系统，就不是接一个大模型 API 那么简单了，得先把整个系统想清楚。
拆需求的时候，能看清这个系统其实包含好几块相对独立又互相依赖的能力，往细了拆每一块又能再分出几个具体的点。对话交互这一块，用户要能直接向 AI 提问并得到实时回复，用户连续追问时系统要记得上下文，不能每次都当新会话处理，回复内容不能只是一段文字还要能展示意图类型、置信度和建议操作快速判断。知识问答这一块，AI 要能基于公司自己上传的售后政策、产品说明、常见问题这类资料回答问题，而不是只靠大模型自带的通用知识，资料要支持管理员上传和更新，回答还要带上引用来源方便核实，不能让用户凭空相信一个没有依据的答案。业务查询与操作这一块，AI 要能在用户提问订单状态、物流进度时主动调用工具去查真实的业务系统，返回的是当前实际数据而不是模型编出来的内容，往后还要能查工单、查用户资料，甚至协助创建新工单。风险控制这一块，退款、改订单状态、执行数据库操作这类会产生实际影响的操作，不能让 AI 自己拍板执行，必须有人工审核这道关卡，审核人员要能看到 AI 建议做什么、调用了什么工具、传了什么参数，再决定通过、拒绝还是修改后通过。权限管理这一块，不同角色能看到和操作的功能不一样，普通员工可能只能问知识库，客服能查订单和工单，主管能审核高风险操作，管理员能管理知识库和系统配置，这意味着系统里从第一天起就要考虑角色和权限的边界。效果验证这一块，系统跑起来之后不能只凭感觉说好用，得有办法量化 AI 回答的准确率、知识库召回是否命中正确文档、工具调用有没有出错，上线前后都要能拿出数据说话。这几块能力凑在一起，才是业务方真正想要的东西，而不是一个孤立的聊天窗口。
把上面这段话拆成表格会更清楚，方便对照后面每一周对应要实现哪块能力。
| 需求点 | 具体诉求 | 对应能力 |
|---|---|---|
| 对话交互 | 用户提问能实时得到回复，连续追问要记得上下文，回复要能展示意图、置信度和建议操作 | 聊天主链路、会话管理、结构化输出 |
| 知识问答 | AI 回答要基于公司上传的资料，资料可更新，回答要带引用来源 | 知识库管理与检索（RAG） |
| 业务查询与操作 | AI 能查订单、查工单、查用户资料，返回真实业务系统的数据 | 工具调用（Agent Tools） |
| 风险控制 | 退款、改状态、执行 SQL 这类操作不能让 AI 自行拍板，需要人工审核 | 人工审核（Human-in-the-loop） |
| 权限管理 | 不同角色看到和能操作的功能不一样，从员工到管理员权限逐级放开 | 用户角色与权限控制 |
| 效果验证 | 上线前后要能量化回答准确率、知识库召回率、工具调用成功率 | 评估体系 |
二、画系统架构
把这些需求整理清楚之后，再来看系统架构就顺理成章了。前端是一个管理后台，包含对话页面、知识库管理页面、工单处理页面、人工审核页面、Agent 执行过程页面、评估报告页面和系统配置页面，这些页面对应的正是前面拆出来的每一块业务能力。后端对应地拆成 FastAPI 接口层、Agent 服务、RAG 服务、工具调用服务、审批服务、评估服务和用户权限服务，各自负责一块职责，避免一个模块把所有逻辑都揽在自己身上。再往下是基础设施层，包括 PostgreSQL 存业务数据、Redis 做缓存和会话状态、Qdrant 或 pgvector 存向量、LangSmith 做可观测性、Docker Compose 负责把这些服务组织起来统一部署。这套架构在第一天只是画出来定个方向，具体每一块能力会在接下来几周里逐步实现，但先把整体形状定下来，后面每天的开发才有地方安放。
整套架构画成图会更直观，大致是前端管理后台调用后端接口层，接口层把请求分发给 Agent 服务，Agent 服务再按需调用 RAG 服务、工具调用服务和审批服务，所有服务最终落到底层的数据库、向量库和缓存上，观测和部署则贯穿整个系统。
三、创建前后端项目
架构定下来之后，第一天真正要动手的就是把前后端的项目骨架分别搭起来，后端和前端各自选用什么技术、目录怎么分层，下面分开来看。
3.1 后端项目骨架
第一天真正要动手的是把后端的项目骨架搭起来，第一天真正要动手的是把前后端的项目骨架搭起来。后端选择 Python 加 FastAPI，项目结构里 main.py 作为服务入口，api 目录放接口路由，agents 目录放 Agent 相关逻辑，rag 目录放检索增强相关代码，tools 目录放工具调用的封装，schemas 目录放请求和响应用到的数据结构定义，这样划分是因为接下来几周会陆续往这几个目录里添加代码，提前分好类目，后面加功能的时候就不用再纠结代码该放哪。
backend/
├── app/
│ ├── main.py
│ ├── api/
│ ├── agents/
│ ├── rag/
│ ├── tools/
│ └── schemas/
└── requirements.txt
3.2 前端项目骨架
前端用 Vite 搭配 Vue 3 初始化，目录结构上 api 目录统一放和后端交互的请求封装，views 目录放各个页面级组件，components 目录放页面内部可复用的小组件，router 目录管理路由和权限跳转，stores 目录用 Pinia 管理跨页面共享的状态，main.ts 作为应用入口。这套分层和后端的目录划分是对应的，页面越往后越多，组件也会越拆越细，第一天先把骨架定好，能省掉后面大量的目录调整成本。
frontend/
├── src/
│ ├── api/
│ ├── views/
│ ├── components/
│ ├── router/
│ ├── stores/
│ └── main.ts
├── package.json
└── vite.config.ts
四、规划页面结构
项目骨架搭好之后，紧接着要把页面路由规划出来。这一步不是要把每个页面都做完，而是先把整个系统未来会有哪些页面想清楚，落到路由表里，后面每一周的开发本质上就是把这些路由背后的页面逐个填充完整。对话页面 /chat 是用户和 AI 交互的主入口，知识库文档管理页面 /documents 负责公司资料的上传和管理，工单列表 /tickets 和工单详情 /tickets/:id 对应客服日常处理工单的场景，人工审核页面 /approvals 是高风险操作的把关环节，Agent 执行记录页面 /traces 用来查看 AI 每一步做了什么，评估报告页面 /evaluations 用来衡量系统上线前后的效果，系统配置页面 /settings 留给模型、权限这些系统级参数的管理。
/chat AI 对话页面
/documents 知识库文档管理
/tickets 工单列表
/tickets/:id 工单详情
/approvals 人工审核
/traces Agent 执行记录
/evaluations 评估报告
/settings 系统配置
五、跑通本地开发环境
最后一步是把本地开发环境跑起来，验证前后端两个项目都能正常启动。后端装好依赖之后用 Uvicorn 把 FastAPI 服务跑起来，前端用 Vite 的开发服务器启动，两边分别监听各自的端口，这一步不涉及具体业务逻辑，纯粹是确认项目骨架没有问题、依赖都能装上、服务都能起来。这一天结束时手上还看不到任何实际功能，页面打开是空的，接口也没有真正的业务逻辑，但目录结构、技术选型、路由规划这些决定后续几周开发节奏的东西都已经定下来了。明天要做的就是让 /chat 页面第一次真正能对话起来。
六、今天要装的依赖包
今天只是把骨架搭起来，还没写业务逻辑，所以依赖也只需要装能让项目跑起来的最基础那一批，后面几周涉及 RAG、向量库、Agent 框架时再逐步补充。
后端在 backend/ 目录下需要安装这些包，写进 requirements.txt。
fastapi==0.139.0
uvicorn[standard]==0.49.0
pydantic==2.13.4
python-dotenv==1.2.2
fastapi 是接口层框架本身，uvicorn 是运行 FastAPI 应用的 ASGI 服务器，装的时候带上 [standard] 是为了拿到自动重载和更完整的日志输出，本地开发改代码不用手动重启服务。pydantic 是 FastAPI 内置依赖的数据校验库，这里显式锁定版本，是因为后面几周会用到它做请求体和响应体的结构化定义，先固定版本避免中途升级带来兼容问题。python-dotenv 用来读取本地的 .env 文件，第一天虽然还没有需要保密的配置项，但数据库连接串、模型 API Key 这些迟早要用环境变量管理，提前装上不用等到要用的时候再补。
安装命令在 backend/ 目录下执行。
pip install -r requirements.txt
前端在 frontend/ 目录下需要安装这些包，写进 package.json 的依赖里。
{
"dependencies": {
"axios": "^1.18.1",
"pinia": "^3.0.4",
"vue": "^3.5.39",
"vue-router": "^5.1.0"
}
}
vue 是前端框架本身，vue-router 对应前面规划的 /chat、/documents、/tickets 这些路由，第一天虽然页面还是空的，但路由跳转和后面要做的权限控制都得靠它撑起来。pinia 用来管理跨页面共享的状态，比如登录用户信息、当前会话 ID，这类状态不适合每个页面各自维护一份，提前引入能避免后面为了共享状态而临时改造组件结构。axios 负责和后端接口通信，api 目录下的请求封装都会基于它来写，第一天先装上，接口调通的时候不用再回头补依赖。
安装命令在 frontend/ 目录下执行，用 Vite 初始化项目时这几个包大多会被脚手架自动带上，如果没有可以手动补装。
npm install vue vue-router pinia axios
七、总结
这一天没有写一行业务逻辑，做的都是打地基的事，但恰恰是这些地基决定了后面二十天能不能顺利往下走。需求拆清楚之后，才知道对话交互、知识问答、业务查询、风险控制、权限管理、效果验证这六块能力分别对应第几周要做的事，不至于走到中途才发现漏了一块没考虑。系统架构画出来之后，前端管理后台、后端各服务模块、底层基础设施之间的调用关系有了图可以对照，后面每加一个功能都知道该放在架构的哪一层。前后端项目骨架搭起来之后，代码从第一天起就有地方安放，不会出现功能越堆越多、目录越来越乱的情况。页面路由规划出来之后，/chat、/documents、/tickets 这些入口虽然现在还是空的，但已经把整个系统未来的样子提前定了型。本地开发环境跑通之后，至少确认了这套技术选型在本机上是可行的，不会在后面某一天突然卡在环境问题上。
这几件事看起来琐碎，但省掉的是后面反复推翻重来的成本。明天开始就要正式往这个空壳里填内容，第一步是让 /chat 页面第一次真正能和 AI 对话起来，把今天画在图上的聊天主链路变成用户能亲手体验的功能。
浙公网安备 33010602011771号