공식 SDK 마이그레이션
기존 OpenAI, Anthropic 또는 Gemini SDK 애플리케이션을 AGTCloud에 연동하고 호환성 경계를 체계적으로 확인합니다.
애플리케이션이 OpenAI, Anthropic 또는 Gemini SDK를 이미 사용한다면 보통 기존 SDK와 업무 프레임워크를 유지하고 클라이언트를 AGTCloud의 같은 종류의 호환 프로토콜에 연결할 수 있습니다. 마이그레이션은 주소 교체에 그치지 않으며 인증, 모델 ID, 자동 경로 조합, 요청 필드 및 응답 파싱을 함께 확인해야 합니다.
같은 프로토콜을 유지합니다
OpenAI, Anthropic Messages 및 Gemini Generate Content는 서로 다른 세 가지 프로토콜입니다. 같은 프로토콜 안에서 서비스 주소를 교체하고 프로토콜도 바꾸려면 완전한 인터페이스 리팩터링으로 설계하고 테스트합니다.
마이그레이션 전 목록 작성
가장 간단한 텍스트 요청만 검증하지 않도록 현재 애플리케이션이 실제로 사용하는 기능을 먼저 기록합니다.
| 확인 항목 | 기록할 내용 |
|---|---|
| SDK | 패키지 이름, 언어, 버전 및 동기 또는 비동기 Client |
| 프로토콜 | Chat Completions, Responses, Messages 또는 Generate Content |
| 모델 | 현재 모델 ID 및 코드에 모델 허용 목록이 있는지 여부 |
| 입력 | 텍스트, 이미지, 파일, 시스템 지시 및 메시지 기록 |
| 출력 | 텍스트 편의 속성, 전체 응답 객체 및 사용자 정의 파싱 로직 |
| Streaming | 이벤트 유형, 증분 결합 및 종료 조건 |
| 도구 | 도구 정의, 호출 ID, 매개변수 파싱 및 결과 전달 |
| 신뢰성 | 타임아웃, 재시도, 요청 제한, 로그 및 폴백 전략 |
최소 변경
세 SDK 모두 다음 설정을 확인해야 하지만 입력 방식은 SDK에 따라 다릅니다.
| 설정 | 마이그레이션 조치 |
|---|---|
| API 주소 | 해당 튜토리얼의 Origin 또는 Base URL을 사용하고 SDK의 버전 경로 자동 추가 여부를 확인합니다 |
| API Key | 환경 변수에서 AGTCloud API Key를 읽고 소스 코드나 저장소에 기록하지 않습니다 |
| 모델 ID | 현재 API Key에 표시되며 대상 프로토콜을 지원하는 모델을 사용합니다 |
| 요청 메서드 | chat.completions.create 또는 messages.create 등의 기존 프로토콜 Client 메서드를 유지합니다 |
| 응답 읽기 | AGTCloud Reference와 비교하여 텍스트, 도구, Usage 및 오류 구조를 확인합니다 |
SDK별 마이그레이션
OpenAI SDK는 Chat Completions와 Responses를 호출할 수 있습니다. AGTCloud Base URL에는 /v1이 포함됩니다.
| 마이그레이션 전 | 마이그레이션 후 |
|---|---|
| 기존 서비스 API Key | AGTCLOUD_API_KEY 환경 변수 |
| 기존 서비스 Base URL 또는 SDK 기본 주소 | https://api.agtcloud.cn/v1 |
| 기존 모델 이름 | 현재 API Key에 표시되는 MODEL_ID |
| 기존 Chat 또는 Responses 메서드 | 동일한 Client 메서드 유지 |
/v1을 중복 추가하지 않습니다
https://api.agtcloud.cn/v1에는 이미 버전 경로가 포함됩니다. https://api.agtcloud.cn/v1/v1로 다시 설정하거나 전체 /chat/completions 또는 /responses 엔드포인트를 입력하지 않습니다.
전체 설치, Client 초기화 및 Python, TypeScript 예시는 OpenAI SDK를 확인합니다.
세 가지 설정만 바꿔서는 안 되는 경우
다음 상황에서는 Base URL, Key 및 모델 교체뿐 아니라 업무 코드를 조정해야 합니다.
- 애플리케이션을 Chat Completions에서 Responses로 변경합니다.
- OpenAI, Anthropic 또는 Gemini 프로토콜 사이에서 애플리케이션을 마이그레이션합니다.
- 코드가 특정 SDK의 응답 클래스, 편의 속성 또는 스트리밍 이벤트에 직접 의존합니다.
- 도구 호출에 프로토콜 전용 정의 및 결과 전달 구조를 사용합니다.
- 멀티모달 콘텐츠 블록, 시스템 지시 또는 역할 이름이 바뀝니다.
- SDK가 경로를 자동 조합하지만 기존 프로젝트가 전체 엔드포인트 URL을 전달합니다.
- 애플리케이션이 기존 서비스 전용 모델 검색, 파일 업로드 또는 호스팅 도구에 의존합니다.
마이그레이션 결과 검증
최소 텍스트 요청 검증
Streaming, 도구 또는 멀티모달 콘텐츠를 사용하지 않는 요청을 먼저 보냅니다. 예상한 API 주소로 요청이 전송되고 텍스트 응답을 읽을 수 있는지 확인합니다.
운영에 필요한 기능 복원
Streaming, 도구 호출, 구조화된 출력, 멀티모달 및 다중 턴 상태의 순서로 기능을 복원합니다. 차이를 찾기 쉽도록 한 번에 기능 하나만 추가합니다.
비성공 경로 확인
최소한 유효하지 않은 API Key, 잘못된 모델 ID, 타임아웃, 요청 제한 및 연결 중단을 검증합니다. 애플리케이션이 상태 코드와 오류 정보를 읽고 무한 재시도하지 않는지 확인합니다.
업무 결과 비교
HTTP 200만 확인하지 않습니다. 텍스트 내용, 도구 매개변수, 종료 이유, Usage, 스트리밍 종료 조건 및 로그의 Request ID를 함께 비교합니다.
단계별 전환 및 롤백
- 새 Provider와 기존 Provider의 설정을 독립적으로 유지하고 업무 코드에 주소와 모델 이름을 분산하지 않습니다.
- 먼저 개발 또는 테스트 트래픽에 AGTCloud를 사용한 뒤 범위를 점진적으로 확대합니다.
- 각 단계의 성공률, 지연 시간, 오류 유형 및 기능 차이를 기록합니다.
- 기존 Provider 설정과 통제 가능한 폴백 스위치를 유지하고 안정성을 확인한 뒤 이전 설정을 정리합니다.
묵시적인 무시에 의존하지 않습니다
일부 호환 구현은 알 수 없는 필드를 받아도 해당 기능을 실행하지 않을 수 있습니다. 검증에서는 실제 결과와 응답 구조를 관찰해야 하며 상태 코드만으로 필드 적용 여부를 판단해서는 안 됩니다.
다음 단계
- SDK 개요에서 해당 튜토리얼을 선택합니다.
- API Key, Base URL 및 인증을 확인합니다.
- Chat에서 Responses로 마이그레이션하려면 Chat Completions → Responses를 이어서 읽습니다.
- 상태 코드 또는 요청 실패가 발생하면 오류 및 문제 해결을 참고합니다.