这是这个专栏的第一篇接下来会花二十天时间把一个企业级 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 服务、工具调用服务和审批服务所有服务最终落到底层的数据库、向量库和缓存上观测和部署则贯穿整个系统。基础设施后端服务前端管理后台对话/知识库/工单/审核/追踪/评估/配置页面FastAPI 接口层Agent 服务RAG 服务工具调用服务审批服务评估服务用户权限服务PostgreSQLRedisQdrant / pgvectorLangSmith 可观测性Docker Compose三、创建前后端项目架构定下来之后第一天真正要动手的就是把前后端的项目骨架分别搭起来后端和前端各自选用什么技术、目录怎么分层下面分开来看。3.1 后端项目骨架第一天真正要动手的是把后端的项目骨架搭起来第一天真正要动手的是把前后端的项目骨架搭起来。后端选择 Python 加 FastAPI项目结构里main.py作为服务入口api目录放接口路由agents目录放 Agent 相关逻辑rag目录放检索增强相关代码tools目录放工具调用的封装schemas目录放请求和响应用到的数据结构定义这样划分是因为接下来几周会陆续往这几个目录里添加代码提前分好类目后面加功能的时候就不用再纠结代码该放哪。backend/ ├── app/ │ ├── main.py │ ├── api/ │ ├── agents/ │ ├── rag/ │ ├── tools/ │ └── schemas/ └── requirements.txt3.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。fastapi0.139.0 uvicorn[standard]0.49.0 pydantic2.13.4 python-dotenv1.2.2fastapi是接口层框架本身uvicorn是运行 FastAPI 应用的 ASGI 服务器装的时候带上[standard]是为了拿到自动重载和更完整的日志输出本地开发改代码不用手动重启服务。pydantic是 FastAPI 内置依赖的数据校验库这里显式锁定版本是因为后面几周会用到它做请求体和响应体的结构化定义先固定版本避免中途升级带来兼容问题。python-dotenv用来读取本地的.env文件第一天虽然还没有需要保密的配置项但数据库连接串、模型 API Key 这些迟早要用环境变量管理提前装上不用等到要用的时候再补。安装命令在backend/目录下执行。pipinstall-rrequirements.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 初始化项目时这几个包大多会被脚手架自动带上如果没有可以手动补装。npminstallvue vue-router pinia axios七、总结这一天没有写一行业务逻辑做的都是打地基的事但恰恰是这些地基决定了后面二十天能不能顺利往下走。需求拆清楚之后才知道对话交互、知识问答、业务查询、风险控制、权限管理、效果验证这六块能力分别对应第几周要做的事不至于走到中途才发现漏了一块没考虑。系统架构画出来之后前端管理后台、后端各服务模块、底层基础设施之间的调用关系有了图可以对照后面每加一个功能都知道该放在架构的哪一层。前后端项目骨架搭起来之后代码从第一天起就有地方安放不会出现功能越堆越多、目录越来越乱的情况。页面路由规划出来之后/chat、/documents、/tickets这些入口虽然现在还是空的但已经把整个系统未来的样子提前定了型。本地开发环境跑通之后至少确认了这套技术选型在本机上是可行的不会在后面某一天突然卡在环境问题上。这几件事看起来琐碎但省掉的是后面反复推翻重来的成本。明天开始就要正式往这个空壳里填内容第一步是让/chat页面第一次真正能和 AI 对话起来把今天画在图上的聊天主链路变成用户能亲手体验的功能。