模型迁移流程

当前迁移问题

下表显示了当前标记为 AI Model Migration 的开放问题。这提供了 GitLab 全局范围内正在进行的模型迁移工作的实时视图。

display: table
fields: title, author, assignee, milestone, labels, updated
limit: 10
query: label = "AI Model Migration" AND opened = true

注意：此表在查看渲染文档时使用 GitLab 查询语言 (GLQL) 动态生成。它显示最多 10 个带有 AI Model Migration 标签的开放问题，按最近更新时间排序。

快速链接

• GitLab AI 功能 - 默认 GitLab AI 供应商模型: 查看所有功能及其当前模型映射
• AI 模型版本迁移计划史诗: 所有模型迁移工作的中央跟踪史诗
• AI Gateway 仓库: 管理模型配置的地方
• 提示词库: 用于评估模型和提示词

引言

LLM 模型不断发展，GitLab 需要定期更新我们的 AI 功能以支持更新的模型。本指南提供了一种结构化的方法，用于将 AI 功能迁移到新模型，同时保持稳定性和可靠性。

注意：GitLab 致力于利用最新的 AI 模型能力来帮助提供最佳性能和功能，这意味着来自现有 GitLab 子处理器的模型更新可能会在文档更新之外，没有特定的客户通知。

模型迁移时间线

模型迁移通常遵循以下一般时间线：

• 简单模型更新（同一供应商）：1-2 周

  • 示例：从 Claude Sonnet 3.5 升级到 3.7
  • 涉及模型验证、测试和分阶段发布
  • 主要关注保持稳定性和性能

• 复杂迁移：1-2 个月（完整里程碑或更长）

  • 示例：添加对 AWS Bedrock 等新供应商的支持
  • 示例：具有破坏性更改的主要版本升级（例如从 Claude 2 到 3）
  • 需要大量的 API 集成工作
  • 可能需要基础设施更改

时间线因素

多个因素可能会影响迁移时间线：

• 当前系统稳定性和最近的事件
• 资源可用性和竞争优先级
• 新模型中行为变化的复杂性
• 所需测试的规模
• 功能标志发布策略

最佳实践

• 在初始时间线估计上总是谨慎行事
• 使用功能标志进行渐进式发布以最小化风险
• 计划缓冲时间来处理意外问题
• 优先考虑系统稳定性而非部署速度

团队职责

模型迁移涉及多个团队协作。本节明确了哪些团队负责迁移过程的不同方面。

模型迁移的 RACI 矩阵

R = 负责执行，A = 负责问责，C = 咨询，I = 知情

迁移过程

标准迁移过程

1. 初始化

   • AI Framework 团队在 AI 模型版本迁移计划史诗 中创建一个问题
   • 问题应使用命名约定：AI Model Migration - 供应商/模型/版本
   • 应用 AI Model Migration 标签
   • AI Framework 团队将模型配置添加到 AI Gateway
   • AI Framework 团队验证基础设施兼容性

2. 功能团队实施

   • 功能团队创建实施计划
   • 功能团队根据需要调整提示词
   • 功能团队实现功能标志以进行控制发布

3. 测试和验证

   • 功能团队针对新模型运行评估
   • AI Framework 团队提供评估支持

4. 部署

   • 功能团队管理功能标志发布
   • 功能团队监控性能并进行调整

5. 完成

   • 迁移完成后，功能团队移除功能标志
   • 功能团队更新文档

模型弃用过程

1. 识别和规划

   • AI Framework 团队监控供应商公告
   • AI Framework 团队创建一个史诗：用 [替代模型] 替换已弃用的 [模型]
   • 史诗应具有 AI Model Migration 标签
   • 在供应商截止日期前至少 2-4 周设置截止日期
   • AI Framework 团队识别替代模型

2. 评估

   • AI Framework 团队评估替代模型
   • 功能团队使用候选模型测试受影响的功能
   • 团队确定最佳替代模型

3. 实施

   • AI Framework 团队创建模型配置文件
   • 功能团队更新功能以使用替代模型
   • 团队实现功能标志以进行控制发布

4. 测试

   • 功能团队运行全面评估
   • 团队记录性能指标

5. 部署

   • 功能团队通过功能标志管理分阶段发布
   • 团队密切监控性能
   • 根据性能逐渐扩大发布范围

6. 完成

   • 迁移完成后移除功能标志
   • 更新文档
   • 清理已弃用模型的引用

模型迁移的先决条件

在开始模型迁移之前：

1. 在 AI 模型版本迁移计划史诗 下创建一个问题：

   • 标记为 group::ai framework 和 AI Model Migration
   • 记录行为变化或改进
   • 包含任何破坏性更改或兼容性问题
   • 引用供应商文档

2. 验证 AI Gateway 中的模型支持：

   • 检查模型定义：
     • 对于 LiteLLM 模型：ai_gateway/models/v2/container.py
     • 对于 Anthropic 模型：ai_gateway/models/anthropic.py
     • 对于新供应商：创建新的模型定义文件
   • 验证配置（枚举、停止标记、超时等）
   • 在本地测试模型：
     • 设置 AI gateway 开发环境
     • 在 .env 文件中配置 API 密钥
     • 使用 http://localhost:5052/docs 上的 Swagger UI 进行测试
   • 如需要，为新模型支持创建一个问题
   • 查看供应商 API 文档以了解破坏性更改

3. 确保访问测试环境和监控工具

4. 使用 提示词库 完成模型评估

模型弃用的额外先决条件

对于模型弃用：

1. 在宣布弃用时创建一个史诗：

   • 标记为 group::ai framework 和 AI Model Migration
   • 记录弃用时间线
   • 包含供应商迁移建议
   • 引用弃用公告
   • 列出所有受影响的功能

2. 评估替代模型：

   • 记录评估标准
   • 运行比较评估
   • 考虑区域可用性
   • 评估所需的基础设施更改

3. 创建迁移时间线：

   • 在截止日期前至少 2-4 周设置完成目标
   • 为每个功能更新预留时间
   • 计划渐进式发布
   • 为基础设施更改预留时间

实施指南

功能团队迁移模板

功能团队应使用 AI 模型发布模板 来实施模型迁移。请参阅我们的 Claude 3.7 Sonnet 代码生成发布计划 中的示例。

Anthropic 模型迁移任务

AI Framework 团队：

• 将新模型添加到 AI Gateway 配置
• 验证与当前 API 规范的兼容性
• 验证模型与现有 API 模式的兼容性
• 创建模型配置文件
• 记录模型特定参数或行为
• 验证基础设施兼容性
• 按照 提示词定义指南 更新模型定义

功能团队：

• 将新模型添加到 可用模型列表
• 在功能标志后更改 AI-Gateway 客户端 中的默认模型
• 更新功能特定代码中的模型引用
• 实现功能标志以进行控制发布
• 使用新模型测试提示词
• 在发布期间监控性能
• 更新文档

Vertex 模型迁移任务

AI Framework 团队：

• 在 Google Cloud Platform 中激活模型
• 更新 AI Gateway 以支持新的 Vertex 模型
• 记录模型特定参数

功能团队：

• 更新功能特定代码中的模型引用
• 实现功能标志以进行控制发布
• 使用新模型测试提示词
• 在发布期间监控性能
• 更新文档

功能标志实现

实施步骤

有关实施功能标志的信息，请参阅我们的 功能标志开发指南。

模型选择实施

在以下位置实现模型选择逻辑：

• AI Gateway 客户端 (ee/lib/gitlab/llm/chain/requests/ai_gateway.rb)
• AI Gateway 中的模型定义
• 特定功能中的任何自定义实现

发布策略

1. 为小部分用户/组启用功能标志
2. 使用以下工具监控性能：
   • Sidekiq 服务仪表板
   • AI Gateway 指标仪表板
   • AI Gateway 日志
   • 功能使用仪表板
   • Periscope 仪表板
3. 逐渐增加发布百分比
4. 如果出现问题，禁用功能标志以回滚
5. 一旦稳定，移除功能标志

常见迁移场景

简单模型版本更新（同一供应商）

示例：从 Claude 3.5 升级到 Claude 3.7

AI Framework 团队：

• 创建迁移问题
• 添加模型配置文件
• 验证 API 兼容性
• 确保基础设施支持

功能团队：

• 创建实施问题
• 使用新模型测试提示词
• 实施功能标志
• 监控性能
• 稳定后移除功能标志

新供应商集成

示例：添加 AWS Bedrock 模型

AI Framework 团队：

• 创建集成计划
• 在 AI Gateway 中实现供应商 API
• 创建模型配置文件
• 更新身份验证机制
• 记录供应商特定参数
• 评估模型性能

功能团队：

• 使用新模型评估功能质量和性能
• 为新供应商的模型调整提示词
• 实施功能标志
• 部署和监控
• 更新文档

模型弃用响应

示例：替换已弃用的 Vertex AI Code Gecko v2

AI Framework 团队：

• 创建史诗以跟踪弃用
• 评估替代模型
• 创建模型配置
• 记录路由逻辑
• 验证基础设施兼容性

功能团队：

• 实施路由逻辑
• 为过渡创建功能标志
• 运行评估
• 实施分阶段发布
• 在过渡期间监控性能

故障排除指南

提示词兼容性问题

如果您遇到提示词兼容性问题：

1. 分析错误：

   • 启用"扩展 AI 日志"以捕获模型响应
   • 检查"LLM 未遵循指令"错误
   • 检查模型输出中是否有意外模式

2. 解决问题：

   • 创建新的提示词版本（遵循语义版本控制）
   • 在评估环境中测试提示词变体
   • 使用功能标志控制提示词部署
   • 在发布期间监控性能

示例：从 Claude 3.5 到 3.7 的迁移

对于 Claude 3.7 迁移：

• 创建新的版本 2.0.0 提示词定义
• 实施提示词版本控制的功能标志
• 使用 AI Framework 团队的模型配置文件
• 运行评估以验证性能
• 逐步发布并监控

AI Framework 团队迁移问题模板

AI Framework 团队应按照此模板创建主要的迁移问题：

# [模型名称] 模型升级

## 概述
[新模型的简要描述及其改进]

## 需要更新的功能
[受此迁移影响的功能列表，按类别组织]

### 正式发布的功能
- [功能 1]
- [功能 2]

### Beta 功能
- [Beta 功能 1]

### 实验性功能
- [实验性功能 1]

## 所需更改
- 添加模型配置文件以实现模型灵活性
- 创建新提示词定义以使用新模型
- 创建功能标志以进行控制发布

## 技术细节
- [关于此迁移的任何技术细节]
- [对 GitLab.com 和 GitLab 自托管实例的影响]

## 实施步骤
- [ ] 更新每个功能中的模型配置
- [ ] 验证性能改进
- [ ] 部署更新
- [ ] 更新文档

## 时间线
优先级：[优先级]

## 参考资料
- [模型公告]
- [模型文档]
- [GitLab 文档]
- [其他相关链接]

## 提议的解决方案
[高级实施方法的描述]

## 实施细节

按照以下问题及其相关的发布计划：

| 功能 | DRI | 预计完成时间 | 问题链接 |
|---------|-----|-----|------------|
| [功能 1] | [@用户名] | [日期] | [问题链接] |
| [功能 2] | [@用户名] | [日期] | [问题链接] |

请参阅我们的 Claude 3.7 模型升级 问题中的示例。

参考资料

• 模型文档

  • Anthropic 模型文档
  • Google Vertex AI 文档

• GitLab 资源

  • GitLab AI 功能 - 默认 GitLab AI 供应商模型
  • AI Gateway 仓库
  • 提示词库
  • AI 模型版本迁移计划