모델 마이그레이션 프로세스
GitLab v19.1아래 표는 AI Model Migration 라벨이 지정된 현재 열린 이슈를 보여줍니다. 이 표는 렌더링된 문서를 볼 때 GitLab Query Language(GLQL)를 사용하여 동적으로 생성됩니다. GitLab AI Features - Default GitLab AI Vendor Models: 모든 기능과 현재 모델 매핑을 확인합니다.
현재 마이그레이션 이슈#
아래 표는 AI Model Migration 라벨이 지정된 현재 열린 이슈를 보여줍니다. GitLab 전반에서 진행 중인 모델 마이그레이션 작업의 실시간 현황을 확인할 수 있습니다.
display: table
fields: title, author, assignee, milestone, labels, updated
limit: 10
query: label = "AI Model Migration" AND opened = true
이 표는 렌더링된 문서를 볼 때 GitLab Query Language(GLQL)를 사용하여 동적으로 생성됩니다. AI Model Migration 라벨이 있는 열린 이슈 최대 10건을 최근 업데이트 순으로 표시합니다.
빠른 링크#
-
GitLab AI Features - Default GitLab AI Vendor Models: 모든 기능과 현재 모델 매핑을 확인합니다.
-
AI Model Version Migration Initiative Epic: 모든 모델 마이그레이션 작업을 위한 중앙 추적 에픽
-
AI Gateway Repository: 모델 설정이 관리되는 곳
-
Centralized Evaluation Framework: 모델과 프롬프트 평가에 사용
소개#
LLM 모델은 지속적으로 발전하고 있으며, GitLab은 최신 모델을 지원하기 위해 AI 기능을 정기적으로 업데이트해야 합니다. 이 가이드는 안정성과 신뢰성을 유지하면서 AI 기능을 새 모델로 마이그레이션하는 구조적인 접근 방식을 제공합니다.
GitLab은 최적의 성능과 기능을 제공하기 위해 최신 AI 모델 역량을 활용하려고 노력합니다. 이는 기존 GitLab 하위 처리자의 모델 업데이트가 문서 업데이트 외에 특별한 고객 알림 없이 이루어질 수 있음을 의미합니다.
모델 마이그레이션 일정#
모델 마이그레이션은 일반적으로 다음과 같은 일정을 따릅니다:
- 단순 모델 업데이트(동일 제공업체): 1-2주
예: Claude Sonnet 3.5에서 3.7로 업그레이드
-
모델 검증, 테스트, 단계적 롤아웃 포함
-
안정성과 성능 유지에 초점
-
복잡한 마이그레이션: 1-2개월(전체 마일스톤 이상)
예: AWS Bedrock과 같은 새 제공업체 지원 추가
-
예: 브레이킹 체인지가 있는 주요 버전 업그레이드(예: Claude 2에서 3으로)
-
상당한 API 통합 작업 필요
-
인프라 변경이 필요할 수 있음
일정 영향 요인#
마이그레이션 일정에 영향을 미치는 여러 요인:
-
현재 시스템 안정성 및 최근 인시던트
-
리소스 가용성과 경쟁 우선순위
-
새 모델의 행동 변화 복잡성
-
필요한 테스트 규모
-
피처 플래그 롤아웃 전략
모범 사례#
-
초기 일정 추정 시 항상 신중한 쪽으로 결정할 것
-
위험을 최소화하기 위해 점진적 롤아웃에 피처 플래그 사용
-
예상치 못한 문제를 처리할 여유 시간 계획
-
배포 속도보다 시스템 안정성 우선
일부 마이그레이션은 기술적으로 빠르게 완료될 수 있지만, 적절한 테스트와 단계적 롤아웃을 보장하기 위해 일반적으로 더 긴 일정을 계획합니다. 이 접근 방식은 시스템 안정성과 신뢰성을 유지하는 데 도움이 됩니다.
팀 책임#
모델 마이그레이션에는 여러 팀이 함께 작업합니다. 이 섹션에서는 마이그레이션 프로세스의 각 측면에 대해 어떤 팀이 책임지는지를 명확히 합니다.
모델 마이그레이션을 위한 RACI 매트릭스#
| 작업 | AI Framework | Feature Teams | Product | Infrastructure |
|---|---|---|---|---|
| 모델 설정 파일 생성 | R/A | C | I | I |
| 인프라 호환성 | R/A | I | I | C |
| 기능별 프롬프트 조정 | C | R/A | I | I |
| 평가 및 테스트 | C | R/A | I | I |
| 피처 플래그 구현 | C | R/A | I | I |
| 롤아웃 계획 | C | R/A | C | I |
| 문서 업데이트 | C | R/A | C | I |
| 모니터링 및 인시던트 대응 | C | R/A | I | C |
R = 담당(Responsible), A = 책임(Accountable), C = 협의(Consulted), I = 정보 수신(Informed)
마이그레이션 프로세스#
모델 매핑 리소스: GitLab AI Features - Default GitLab AI Vendor Models 페이지에서 각 기능이 어떤 모델과 버전을 사용하는지 확인할 수 있습니다.
표준 마이그레이션 프로세스#
초기화(Initialization)
AI Framework 팀이 AI Model Version Migration Initiative Epic에 이슈를 생성합니다.
-
이슈는 다음 네이밍 규칙을 사용해야 합니다:
AI Model Migration - Provider/Model/Version -
AI Model Migration라벨 적용 -
AI Framework 팀이 AI Gateway에 모델 설정 추가
-
AI Framework 팀이 인프라 호환성 확인
Feature Team 구현
Feature 팀이 구현 계획 수립
-
Feature 팀이 필요 시 프롬프트 조정
-
Feature 팀이 제어된 롤아웃을 위한 피처 플래그 구현
테스트 및 검증
Feature 팀이 새 모델에 대한 평가 실행
-
AI Framework 팀이 평가 지원 제공
배포
Feature 팀이 피처 플래그 롤아웃 관리
-
Feature 팀이 성능 모니터링 및 조정
완료
Feature 팀이 마이그레이션 완료 후 피처 플래그 제거
- Feature 팀이 문서 업데이트
모델 지원 중단 프로세스#
식별 및 계획
AI Framework 팀이 제공업체 공지사항 모니터링
-
AI Framework 팀이 에픽 생성:
Replace discontinued [model] with [replacement] -
에픽에
AI Model Migration라벨 적용 -
제공업체 종료 일자보다 최소 2-4주 전으로 마감일 설정
-
AI Framework 팀이 대체 모델 식별
지원 중단 공지
AI Framework 팀이 ai_gateway/model_selection/models.yml의 모델 항목에 deprecation 블록 추가(모델 지원 중단 지침 참고)
-
(선택 사항) Marketing/AI Partnership이 모델 지원 중단에 관한 블로그 포스트 게시
평가
AI Framework 팀이 대체 모델 평가
-
Feature 팀이 후보 모델로 영향받은 기능 테스트
-
팀이 최적의 대체 모델 결정
구현
AI Framework 팀이 모델 설정 파일 생성
-
Feature 팀이 대체 모델을 사용하도록
ai_gateway/model_selection/unit_primitives.yml업데이트
테스트
Feature 팀이 포괄적인 평가 실행
-
팀이 성능 지표 문서화
배포
팀이 성능 면밀히 모니터링
-
성능에 따라 점진적으로 롤아웃 확대
완료
문서 업데이트
- 지원 중단된 모델 참조 정리
모델 마이그레이션 전제 조건#
모델 마이그레이션을 시작하기 전:
AI Model Version Migration Initiative epic 아래에 이슈를 생성합니다:
group::ai framework 및 AI Model Migration 라벨 적용
-
행동 변화 또는 개선 사항 문서화
-
브레이킹 체인지 또는 호환성 문제 포함
-
제공업체 문서 참조
AI Gateway에서 모델 지원을 확인합니다:
모델 정의 확인:
LiteLLM 모델의 경우: ai_gateway/models/v2/container.py
-
Anthropic 모델의 경우:
ai_gateway/models/anthropic.py -
새 제공업체의 경우: 새 모델 정의 파일 생성
-
설정 확인(enum, stop 토큰, 타임아웃 등)
-
로컬에서 모델 테스트:
-
.env파일에 API 키 설정 -
http://localhost:5052/docs의 Swagger UI를 사용하여 테스트 -
필요한 경우 새 모델 지원을 위한 이슈 생성
-
브레이킹 체인지에 대한 제공업체 API 문서 검토
테스트 환경 및 모니터링 도구에 대한 접근 권한 확보
Centralized Evaluation Framework를 사용하여 모델 평가 완료
모델 지원 중단에 대한 추가 전제 조건#
모델 지원 중단의 경우:
지원 중단이 발표되면 에픽을 생성합니다:
group::ai framework 및 AI Model Migration 라벨 적용
-
지원 중단 일정 문서화
-
제공업체의 마이그레이션 권장 사항 포함
-
지원 중단 공지 참조
-
영향받는 모든 기능 목록 작성
대체 모델을 평가합니다:
평가 기준 문서화
-
비교 평가 실행
-
지역적 가용성 고려
-
필요한 인프라 변경 사항 평가
마이그레이션 일정을 수립합니다:
종료 일자보다 최소 2-4주 전으로 완료 목표 설정
-
각 기능 업데이트에 필요한 시간 포함
-
점진적 롤아웃 계획
-
인프라 변경을 위한 시간 확보
모델 변경 및 지원 중단 문서화는 영향 추적과 향후 문제 해결에 매우 중요합니다. 항상 마이그레이션 프로세스를 시작하기 전에 이슈를 생성하세요.
구현 가이드라인#
Feature Team 마이그레이션 템플릿#
Feature 팀은 AI Model Rollout 템플릿을 사용하여 모델 마이그레이션을 구현해야 합니다. Claude 3.7 Sonnet Code Generation Rollout Plan에서 예시를 확인하세요.
Anthropic 모델 마이그레이션 작업#
AI Framework 팀:
-
AI Gateway 설정에 새 모델 추가
-
현재 API 명세와의 호환성 확인
-
기존 API 패턴과의 모델 동작 확인
-
모델 설정 파일 생성
-
모델별 파라미터 또는 동작 문서화
-
인프라 호환성 확인
-
프롬프트 정의 가이드라인에 따라 모델 정의 업데이트
Feature 팀:
-
사용 가능한 모델 목록에 새 모델 추가
-
피처 플래그 뒤에서 AI-Gateway 클라이언트의 기본 모델 변경
-
기능별 코드의 모델 참조 업데이트
-
제어된 롤아웃을 위한 피처 플래그 구현
-
새 모델로 프롬프트 테스트
-
롤아웃 중 성능 모니터링
-
문서 업데이트
AI Gateway가 프롬프트를 보유하는 방향으로 전환하는 중이지만, 피처 플래그 구현은 여전히 GitLab 릴리즈가 필요합니다.
Vertex 모델 마이그레이션 작업#
AI Framework 팀:
-
Google Cloud Platform에서 모델 활성화
-
새 Vertex 모델을 지원하도록 AI Gateway 업데이트
-
모델별 파라미터 문서화
Feature 팀:
-
기능별 코드의 모델 참조 업데이트
-
제어된 롤아웃을 위한 피처 플래그 구현
-
새 모델로 프롬프트 테스트
-
롤아웃 중 성능 모니터링
-
문서 업데이트
롤아웃 전략#
-
피처 플래그를 활성화하여 소수의 사용자/그룹에 적용
-
다음을 사용하여 성능 모니터링:
-
롤아웃 비율을 점진적으로 증가
-
문제가 발생하면 피처 플래그를 비활성화하여 롤백
-
안정화되면 피처 플래그 제거
일반적인 마이그레이션 시나리오#
단순 모델 버전 업데이트(동일 제공업체)#
예시: Claude 3.5에서 Claude 3.7로 업그레이드
AI Framework 팀:
-
마이그레이션 이슈 생성
-
모델 설정 파일 추가
-
API 호환성 확인
-
인프라 지원 확보
Feature 팀:
-
구현 이슈 생성
-
새 모델로 프롬프트 테스트
-
피처 플래그 구현
-
성능 모니터링
-
안정화되면 피처 플래그 제거
새 제공업체 통합#
예시: AWS Bedrock 모델 추가
AI Framework 팀:
-
통합 계획 수립
-
AI Gateway에 제공업체 API 구현
-
모델 설정 파일 생성
-
인증 메커니즘 업데이트
-
제공업체별 파라미터 문서화
-
모델 성능 평가
Feature 팀:
-
새 모델의 기능 품질 및 성능 평가
-
새 제공업체 모델에 맞게 프롬프트 조정
-
피처 플래그 구현
-
배포 및 모니터링
-
문서 업데이트
모델 지원 중단 대응#
예시: 지원 중단된 Vertex AI Code Gecko v2 교체
AI Framework 팀:
-
지원 중단 추적을 위한 에픽 생성
-
모델을 지원 중단으로 표시하고 모델 지원 중단 공지
-
대체 모델 평가
-
모델 설정 생성
-
라우팅 로직 문서화
-
인프라 호환성 확인
Feature 팀:
-
라우팅 로직 구현
-
전환을 위한 피처 플래그 생성
-
평가 실행
-
단계적 롤아웃 구현
-
전환 중 성능 모니터링
문제 해결 가이드#
프롬프트 호환성 문제#
프롬프트 호환성 문제가 발생하면:
오류 분석:
모델 응답을 캡처하기 위해 "expanded AI logging" 활성화
-
"LLM didn't follow instructions" 오류 확인
-
예상치 못한 패턴에 대한 모델 출력 검토
문제 해결:
새 프롬프트 버전 생성(시맨틱 버저닝 준수)
-
평가 환경에서 프롬프트 변형 테스트
-
프롬프트 배포 제어를 위해 피처 플래그 사용
-
롤아웃 중 성능 모니터링
예시: Claude 3.5에서 3.7로 마이그레이션#
Claude 3.7 마이그레이션의 경우:
-
새 버전 2.0.0 프롬프트 정의 생성
-
프롬프트 버전 제어를 위한 피처 플래그 구현
-
AI Framework 팀의 모델 설정 파일 사용
-
성능 확인을 위한 평가 실행
-
점진적으로 롤아웃하고 모니터링
AI Framework 팀 마이그레이션 이슈 템플릿#
AI Framework 팀은 다음 템플릿에 따라 메인 마이그레이션 이슈를 생성해야 합니다:
# [Model Name] Model Upgrade
## Overview
[Brief description of the new model and its improvements]
## Features to Update
[List of features affected by this migration, organized by category]
### Generally Available Features
- [Feature 1]
- [Feature 2]
### Beta Features
- [Beta Feature 1]
### Experimental Features
- [Experimental Feature 1]
## Required Changes
- Add model configuration file for model flexibility
- New prompt definition created to use the new model
- Feature flag created for controlled rollout
## Technical Details
- [Any technical specifics about this migration]
- [Impact on GitLab.com and GitLab Self-Managed instances]
## Implementation Steps
- [ ] Update model configurations in each feature
- [ ] Verify performance improvements
- [ ] Deploy updates
- [ ] Update documentation
## Timeline
Priority: [Priority level]
## References
- [Model Announcement]
- [Model Documentation]
- [GitLab Documentation]
- [Other relevant links]
## Proposed Solution
[Description of the high-level implementation approach]
## Implementation Details
Follow the issues below with the associated rollout plans:
| Feature | DRI | ETA | Issue Link |
|---------|-----|-----|------------|
| [Feature 1] | [@username] | [Date] | [Issue link] |
| [Feature 2] | [@username] | [Date] | [Issue link] |
Claude 3.7 Model Upgrade 이슈에서 예시를 확인하세요.
참고 자료#
- 모델 문서