Manjusaka
·
当我们在维护模型 API 服务时我们在维护什么
内容提要
本文讨论了团队在构建AI服务时的经验教训，强调了项目结构、配置分层、模型版本迭代和可观测性等关键设计原则。通过引入版本子目录和动态注册机制，简化了多版本管理，确保了API的稳定性和可维护性。同时，文章还分享了一些开发流程和CI/CD的最佳实践，以提高团队的工作效率和代码质量。
关键要点
-
团队在构建AI服务时发现项目结构、配置方式和命名不一致，导致新成员需要重新学习。
-
文章总结了维护模型API服务的经验教训，包括项目结构、配置分层、模型版本迭代和可观测性等设计原则。
-
项目目录结构采用版本子目录，确保不同版本的handler和router物理隔离，避免修改老接口。
-
配置分为三层：Secret、App和CLI，确保不同类型的配置独立管理，减少混乱。
-
引入注册表和动态导入机制，使得app.py在添加新版本时无需修改，支持多版本同时运行。
-
模型版本迭代时，遵循不修改已有API路由的原则，确保版本间的兼容性。
-
可观测性方面，每个API版本拥有独立的MetricsRegistry，通过Prometheus隔离监控指标。
-
日常开发流程中，强制使用分支策略和CI流程，确保代码质量和稳定性。
-
发版流程简化为更新版本号、合并到主分支和创建GitHub Release，减少人为干预。
-
经验教训被整理成Claude Code Skill，以便在新项目中直接应用，提升团队效率。
延伸解读
项目结构的重要性
文章强调了项目结构在构建AI服务中的关键作用。统一的目录结构和配置方式可以显著降低新成员的学习成本，避免重复的知识传递。团队应重视项目的初始设计，以便后续的维护和扩展更加顺畅。
模型版本管理的最佳实践
在模型版本迭代中，文章提出了不修改已有API路由的原则，以确保版本间的兼容性。这一做法不仅减少了潜在的错误，还能让新旧版本同时在线，提升服务的稳定性。团队在设计时应考虑到这一点，以避免未来的维护困扰。
可观测性与监控指标
可观测性是维护AI服务的关键，文章中提到每个API版本应拥有独立的MetricsRegistry。这种做法可以有效隔离监控指标，帮助团队在下线旧版本时做出更明智的决策。团队在实施监控时应确保指标的版本感知，以便于后续的分析和优化。
延伸问答
如何设计一个AI服务的项目结构？
项目结构应采用版本子目录，确保不同版本的handler和router物理隔离，以避免修改老接口。
模型API服务的配置应该如何分层？
配置应分为三层：Secret、App和CLI，以确保不同类型的配置独立管理，减少混乱。
如何实现模型版本的迭代而不影响已有API？
遵循不修改已有API路由的原则，新增版本时只需添加新的handler和router，并在注册表中更新。
可观测性在API服务中如何实现？
每个API版本应拥有独立的MetricsRegistry，通过Prometheus隔离监控指标，以便于版本间的监控。
在日常开发中有哪些最佳实践？
强制使用分支策略和CI流程，确保所有变更都经过代码审查和测试，以提高代码质量和稳定性。
如何简化发版流程以减少人为干预？
发版流程应简化为更新版本号、合并到主分支和创建GitHub Release，尽量减少手动操作。
