从零构建可被后端调用的最小模型服务

很多团队第一次接触大模型时，习惯写一段脚本：拼一个提示词，发一次请求，打印一句话，就算跑通了。但这种方式离“服务”还很远。真正的服务需要配置管理、接口契约、错误边界、可测试性，以及被其他系统稳定调用的能力。本文要做的，就是把一次性的模型调用，放进完整的工程结构里，形成一个可被后端框架集成的智能体服务。

一、目标定位：它不是脚本，而是服务

我们要构建的服务，核心特征是“可被调用”。这意味着它需要有清晰的 HTTP 接口、稳定的输入输出结构、可切换的模型配置，以及不依赖真实密钥即可运行的测试能力。整体接口规划如下：

• /health：返回服务状态与当前模型配置，用于探活与配置核对。
• /agent/chat：接收用户消息，依次经过输入护栏、检索增强、工具调用和主模型链路，最终返回回复。
• /agent/today：基于用户档案与打卡记录，生成当日计划。
• /rag/ingest：将文本切块并写入最小检索存储，为后续增强提供素材。

这四个接口覆盖了“探活—对话—业务生成—知识入库”的最小闭环。重点不在于让模型说一句话，而在于让模型调用成为工程结构中的一环。

二、工程分层：配置、DTO、客户端、编排、边界、测试

一个可维护的智能体服务，至少应包含以下层次：

1. 配置层：集中管理模型名称、接口地址、超时时间、开关项。真实模型调用的密钥不写死在代码里，而是通过环境变量注入。
2. DTO 层：定义请求与响应的数据结构。对话请求包含用户标识与消息内容；对话响应包含回复文本、命中的工具、检索片段等元信息。
3. 客户端层：封装对模型服务的调用，统一处理重试、超时与异常转换。上层编排不关心底层是哪种模型。
4. 服务编排层：把护栏、检索、工具、主模型串成一条链路，每一环都可单独替换。
5. 安全边界层：输入护栏负责拦截明显不安全的指令；输出侧做必要过滤，避免敏感信息外泄。
6. 测试反馈层：默认测试使用假客户端或桩数据，不需要真实密钥；只有显式开启时，才走真实模型。

这种分层的价值在于：当模型供应商变更、接口调整或业务规则变化时，改动被限制在某一层内，不会牵一发而动全身。

三、接口设计要点

3.1 健康检查

/health 不应只返回一个 ok。它还应暴露当前加载的模型名称、是否启用真实调用、检索存储的条目数量等。这样在联调时，后端同学一眼就能看出服务是否连到了正确的配置。

3.2 对话入口

/agent/chat 的处理顺序建议固定为：

1. 输入护栏：检查长度、敏感指令、注入攻击特征。
2. 检索增强：根据用户消息从检索存储中召回相关片段。
3. 工具调用：若问题需要计算或查询，先走工具链。
4. 主模型：将上述上下文组装后交给模型生成回复。
5. 输出整理：统一响应结构，附带调试信息。

顺序固定带来两个好处：一是行为可预测，二是每一环都能单独写测试。

3.3 计划生成

/agent/today 的输入是用户档案与打卡记录，输出是结构化的当日计划。它同样可以复用检索与模型链路，只是提示词模板和输出约束不同。建议把“计划生成”视为一种特殊的对话任务，共享底层编排能力。

3.4 文本入库

/rag/ingest 接收原始文本，按固定长度或语义边界切块，写入最小检索存储。存储可以是内存结构，也可以是本地文件，关键是接口稳定，后续可替换为更专业的向量存储。

四、代码块的三类约定

在实现过程中，会出现三类代码块，务必严格区分：

• [执行命令]：在终端复制运行，用于安装依赖或启动服务。
• [写入文件]：把代码完整复制到指定文件，构成项目源码。
• [理解片段，不要复制]：仅用于解释设计意图，帮助理解代码为何这样组织，不要写入项目。

这种区分能避免把说明性代码误当实现代码，减少低级错误。

五、小步验证：每 2 到 4 个文件跑一次

一个常见的失败模式是：写完十几个文件才第一次运行，结果报错堆在一起，根本不知道是哪一步写错了。正确做法是每完成 2 到 4 个文件就做一次轻量验证：

• 写完配置与 DTO 后，先跑一个导入检查。
• 写完客户端后，用桩数据验证调用路径。
• 写完编排后，跑一个不带真实密钥的端到端测试。
• 写完接口后，用本地请求验证响应结构。

每次验证只关注当前新增的部分，错误定位成本会大幅降低。

六、默认可离线，真实调用需显式开启

测试策略上，默认路径不依赖真实模型密钥。做法是：

• 提供一个假客户端，返回固定或可配置的响应。
• 测试用例默认注入假客户端。
• 真实模型测试通过环境变量或命令行参数显式开启。

这样带来的收益是：持续集成环境无需配置密钥即可运行；新成员拉下代码就能跑通全流程；真实调用只在需要验证效果时开启，避免意外消耗。

七、总结

从零搭建一个最小模型服务，关键不在模型本身，而在工程结构。配置、DTO、客户端、服务编排、安全边界、测试反馈必须同时出现，服务才能被后端稳定调用。接口从探活到对话、从计划生成到知识入库，构成一个可扩展的最小闭环。坚持小步验证、默认可离线、真实调用显式开启，能让开发过程可控、可测、可维护。当这套结构跑通后，后续替换模型、扩展工具、升级检索存储，都只是局部改动，而不会推倒重来。