Manjusaka
·
当我们在维护模型 API 服务时我们在维护什么
💡
原文中文，约14700字，阅读约需35分钟。
📝
内容提要
本文讨论了团队在构建AI服务时的经验教训，强调了项目结构、配置分层、模型版本迭代和可观测性等关键设计原则。通过引入版本子目录和动态注册机制，简化了多版本管理，确保了API的稳定性和可维护性。同时，文章还分享了一些开发流程和CI/CD的最佳实践，以提高团队的工作效率和代码质量。
🎯
关键要点
- 团队在构建AI服务时发现项目结构、配置方式和命名不一致，导致新成员需要重新学习。
- 文章总结了维护模型API服务的经验教训，包括项目结构、配置分层、模型版本迭代和可观测性等设计原则。
- 项目目录结构采用版本子目录，确保不同版本的handler和router物理隔离，避免修改老接口。
- 配置分为三层：Secret、App和CLI，确保不同类型的配置独立管理，减少混乱。
- 引入注册表和动态导入机制，使得app.py在添加新版本时无需修改，支持多版本同时运行。
- 模型版本迭代时，遵循不修改已有API路由的原则，确保版本间的兼容性。
- 可观测性方面，每个API版本拥有独立的MetricsRegistry，通过Prometheus隔离监控指标。
- 日常开发流程中，强制使用分支策略和CI流程，确保代码质量和稳定性。
- 发版流程简化为更新版本号、合并到主分支和创建GitHub Release，减少人为干预。
- 经验教训被整理成Claude Code Skill，以便在新项目中直接应用，提升团队效率。
❓
延伸问答
如何设计一个AI服务的项目结构？
项目结构应采用版本子目录，确保不同版本的handler和router物理隔离，以避免修改老接口。
模型API服务的配置应该如何分层？
配置应分为三层：Secret、App和CLI，以确保不同类型的配置独立管理，减少混乱。
如何实现模型版本的迭代而不影响已有API？
遵循不修改已有API路由的原则，新增版本时只需添加新的handler和router，并在注册表中更新。
可观测性在API服务中如何实现？
每个API版本应拥有独立的MetricsRegistry，通过Prometheus隔离监控指标，以便于版本间的监控。
在日常开发中有哪些最佳实践？
强制使用分支策略和CI流程，确保所有变更都经过代码审查和测试，以提高代码质量和稳定性。
如何简化发版流程以减少人为干预？
发版流程应简化为更新版本号、合并到主分支和创建GitHub Release，尽量减少手动操作。
➡️
