1. 项目背景与迭代目标这个项目最初是一个基于大语言模型(LLM)的个人事实记录工具在迭代一阶段实现了基础功能用户可以通过命令行输入日常活动系统会判断这是需要记录的事实、查询请求还是打卡操作并将有效信息以JSONL格式保存到本地。但实际使用中暴露了几个关键问题首先是单用户设计的局限性。所有记录都默认属于同一个用户当团队想共同使用时数据完全混在一起无法区分。其次是测试困难命令行交互方式难以编写自动化测试用例。最严重的是模型行为的不稳定性——同样的输入有时被识别为记录有时被拒绝而像做了啥这样模糊的输入又经常被错误地当作事实记录。关键设计决策迭代二不增加新功能而是通过工程化手段解决稳定性、隔离性和可测试性问题。这体现了先夯实基础再扩展功能的务实开发理念。2. 架构设计与核心改动2.1 HTTP API统一入口将原来的CLI脚本改造成HTTP服务是本次迭代的基础性改动。我们设计了一个统一的API端点app.post(/api/input) async def handle_input(request: InputRequest): # 统一处理所有类型的输入这个设计有几点考量前端/客户端只需要对接一个接口降低集成复杂度便于编写自动化测试脚本为后续的认证、限流等中间件提供统一切入点2.2 多用户隔离方案通过在请求体中强制要求author字段实现用户隔离{ text: 完成了模块A的单元测试, author: 王五 }数据存储层相应调整每个片段都关联author字段。查询时默认只返回当前author的数据只有特殊值authorall时才返回全量数据。这种设计实现简单不需要复杂的权限系统符合最小权限原则通过约定优于配置减少误操作2.3 响应契约设计统一响应结构是保证可测试性的关键{ ok: true, action: record, tool_called: record_fragment, today_fragments: [...], input_text: 原始输入 }特别约定reject/confirm操作必须返回空数组行为判断只依赖action和tool_called字段保留原始输入便于调试这种显式设计避免了客户端需要猜测服务端行为的反模式。3. 关键问题解决方案3.1 低质量输入过滤原始版本中像做了啥这样的模糊输入经常被错误记录。我们通过输入预处理层解决def preprocess_input(text: str) - str: if is_question(text): # 检测疑问句 return query # 强制转为查询 return text配合prompt工程调整确保只有完整的事实陈述才会触发记录操作。这是典型的工程约束补足模型短板的思路。3.2 行为污染问题早期版本中confirm/reject操作有时会返回历史数据片段。通过明确代码约束解决if response.action in (confirm, reject): response.today_fragments [] # 显式置空这体现了重要的设计原则关键契约应该用代码强制保证而不是依赖模型的自觉性。4. 测试策略与用例设计4.1 测试金字塔实践我们采用分层测试策略单元测试覆盖所有工具函数接口测试验证API契约集成测试检查数据流完整性4.2 核心测试用例4.2.1 必填字段校验def test_missing_author(): response post(/api/input, json{text: 测试}) assert response.status_code 400 assert missing author in response.json()[error]4.2.2 作者隔离验证def test_author_isolation(): # 张三记录 post(/api/input, json{text: 张三的任务, author: 张三}) # 李四查询 response post(/api/input, json{text: ?, author: 李四}) assert len(response.json()[today_fragments]) 04.2.3 全量查询控制def test_all_query(): # 先创建测试数据 post(/api/input, json{text: 数据1, author: A}) post(/api/input, json{text: 数据2, author: B}) response post(/api/input, json{text: ?, author: all}) assert len(response.json()[today_fragments]) 25. 经验总结与避坑指南5.1 关键经验契约先行先定义清晰的接口规范再实现业务逻辑显式优于隐式用代码强制关键约束不依赖间接约定测试驱动重要的业务规则必须对应可验证的测试用例5.2 常见陷阱过度依赖模型对关键业务规则需要工程兜底隔离不彻底多用户系统要特别注意数据边界测试遗漏confirm/reject等边界场景容易被忽略5.3 性能优化建议当前实现每次查询都会全量扫描数据文件当数据量增大时可以考虑按author建立二级目录引入轻量级数据库如SQLite为常用查询添加缓存6. 后续演进方向自动化回归将测试用例整合到CI流水线历史数据迁移设计清洗策略处理迭代一的历史数据打卡规则增强处理重复打卡、超时打卡等边界情况这个项目的完整代码已开源在GitHub包含详细的README和测试说明。对于想要实现类似功能的开发者建议从迭代一的稳定基线开始逐步应用本文的工程化改进方案。
LLM项目工程化实践：多用户隔离与API稳定性优化
1. 项目背景与迭代目标这个项目最初是一个基于大语言模型(LLM)的个人事实记录工具在迭代一阶段实现了基础功能用户可以通过命令行输入日常活动系统会判断这是需要记录的事实、查询请求还是打卡操作并将有效信息以JSONL格式保存到本地。但实际使用中暴露了几个关键问题首先是单用户设计的局限性。所有记录都默认属于同一个用户当团队想共同使用时数据完全混在一起无法区分。其次是测试困难命令行交互方式难以编写自动化测试用例。最严重的是模型行为的不稳定性——同样的输入有时被识别为记录有时被拒绝而像做了啥这样模糊的输入又经常被错误地当作事实记录。关键设计决策迭代二不增加新功能而是通过工程化手段解决稳定性、隔离性和可测试性问题。这体现了先夯实基础再扩展功能的务实开发理念。2. 架构设计与核心改动2.1 HTTP API统一入口将原来的CLI脚本改造成HTTP服务是本次迭代的基础性改动。我们设计了一个统一的API端点app.post(/api/input) async def handle_input(request: InputRequest): # 统一处理所有类型的输入这个设计有几点考量前端/客户端只需要对接一个接口降低集成复杂度便于编写自动化测试脚本为后续的认证、限流等中间件提供统一切入点2.2 多用户隔离方案通过在请求体中强制要求author字段实现用户隔离{ text: 完成了模块A的单元测试, author: 王五 }数据存储层相应调整每个片段都关联author字段。查询时默认只返回当前author的数据只有特殊值authorall时才返回全量数据。这种设计实现简单不需要复杂的权限系统符合最小权限原则通过约定优于配置减少误操作2.3 响应契约设计统一响应结构是保证可测试性的关键{ ok: true, action: record, tool_called: record_fragment, today_fragments: [...], input_text: 原始输入 }特别约定reject/confirm操作必须返回空数组行为判断只依赖action和tool_called字段保留原始输入便于调试这种显式设计避免了客户端需要猜测服务端行为的反模式。3. 关键问题解决方案3.1 低质量输入过滤原始版本中像做了啥这样的模糊输入经常被错误记录。我们通过输入预处理层解决def preprocess_input(text: str) - str: if is_question(text): # 检测疑问句 return query # 强制转为查询 return text配合prompt工程调整确保只有完整的事实陈述才会触发记录操作。这是典型的工程约束补足模型短板的思路。3.2 行为污染问题早期版本中confirm/reject操作有时会返回历史数据片段。通过明确代码约束解决if response.action in (confirm, reject): response.today_fragments [] # 显式置空这体现了重要的设计原则关键契约应该用代码强制保证而不是依赖模型的自觉性。4. 测试策略与用例设计4.1 测试金字塔实践我们采用分层测试策略单元测试覆盖所有工具函数接口测试验证API契约集成测试检查数据流完整性4.2 核心测试用例4.2.1 必填字段校验def test_missing_author(): response post(/api/input, json{text: 测试}) assert response.status_code 400 assert missing author in response.json()[error]4.2.2 作者隔离验证def test_author_isolation(): # 张三记录 post(/api/input, json{text: 张三的任务, author: 张三}) # 李四查询 response post(/api/input, json{text: ?, author: 李四}) assert len(response.json()[today_fragments]) 04.2.3 全量查询控制def test_all_query(): # 先创建测试数据 post(/api/input, json{text: 数据1, author: A}) post(/api/input, json{text: 数据2, author: B}) response post(/api/input, json{text: ?, author: all}) assert len(response.json()[today_fragments]) 25. 经验总结与避坑指南5.1 关键经验契约先行先定义清晰的接口规范再实现业务逻辑显式优于隐式用代码强制关键约束不依赖间接约定测试驱动重要的业务规则必须对应可验证的测试用例5.2 常见陷阱过度依赖模型对关键业务规则需要工程兜底隔离不彻底多用户系统要特别注意数据边界测试遗漏confirm/reject等边界场景容易被忽略5.3 性能优化建议当前实现每次查询都会全量扫描数据文件当数据量增大时可以考虑按author建立二级目录引入轻量级数据库如SQLite为常用查询添加缓存6. 后续演进方向自动化回归将测试用例整合到CI流水线历史数据迁移设计清洗策略处理迭代一的历史数据打卡规则增强处理重复打卡、超时打卡等边界情况这个项目的完整代码已开源在GitHub包含详细的README和测试说明。对于想要实现类似功能的开发者建议从迭代一的稳定基线开始逐步应用本文的工程化改进方案。