workers-ai-provider에서 createAI로, 기존 코드는 무엇을 바꿀까?

세 줄 요약

Cloudflare의 기존 AI 제공자 두 패키지는 기능 개발이 동결됐으며, 새 연결 함수는 agents/models/ai-sdk의 createAI다.
기존 앱은 import뿐 아니라 AI SDK 버전, 인증 필드, 모델을 넘기는 방식도 맞춰야 한다.
AI Search는 별도 제공자로 옮기며, fallback과 끊긴 스트림 재개는 적용 조건이 다르다.

먼저 기존 앱이 무엇을 호출하는지 나눈다

workers-ai-provider를 사용하던 앱은 createWorkersAI를 새 제공자의 createAI로 바꾸는 데서 시작한다. Worker 안에서 쓰는 binding은 이어 쓸 수 있지만, 외부 서버에서 쓰던 인증 옵션과 AI Search 호출은 각각 다른 수정이 필요하다.

Cloudflare는 10월 21일 통합 제공자를 발표하면서 workers-ai-provider와 ai-gateway-provider를 deprecated로 표시하고 새 기능 개발을 동결했다. 발표는 기존 앱의 당일 중단을 요구하지 않는다. 사용 중인 호출을 아래처럼 분류하면 이전 범위를 정하기 쉽다.

기존 코드	이전할 곳·변경점
`createWorkersAI` + binding	`agents/models/ai-sdk`의 `createAI`로 바꾼다.
`accountId` + `apiKey`	새 함수에서는 `accountId` + `apiToken`을 쓴다.
`createAiGateway`	`createAI`로 옮기고 여러 모델의 실패 시 전환 방식을 점검한다.
`createAISearch`	`ai-search-provider`의 `createAISearchNamespace`로 옮긴다.

import를 바꾸기 전에 AI SDK 버전을 맞춘다

현재 설치 안내는 ai@^7과 @ai-sdk/provider@^4를 요구한다. 이전 프로젝트의 의존성을 그대로 둔 채 함수 이름만 바꾸면 이 조건을 놓칠 수 있다. 새 제공자는 베타이며 마이너 릴리스에서도 API가 바뀔 수 있다.

Worker에서는 Wrangler 설정에 AI 바인딩을 두고, 요청 처리 코드에서 다음처럼 제공자를 만든다. 아래는 모델을 고르는 부분의 예시다.

import { createAI } from "agents/models/ai-sdk";

const ai = createAI({ binding: env.AI });
const model = ai("@cf/zai-org/glm-4.7-flash");

Worker 밖에서는 계정 ID와 API 토큰을 넘긴다. 인증 문서가 요구하는 권한도 호출 형태에 따라 다르다. 문자열 모델 ID는 Workers AI Read, 공급사의 모델 객체는 AI Gateway Run을 사용한다.

모델 이름 문자열과 공급사의 모델 객체는 경로가 다르다

문자열로 고르는 @cf/…는 Workers AI 모델이다. AI Gateway 카탈로그 ID와 dynamic/… 경로도 문자열로 넘길 수 있다. 이 방식에는 공급사별 AI SDK 패키지가 필요하지 않다.

반면 공급사의 AI SDK로 만든 모델 객체를 ai()로 감싸면, 공급사 패키지가 요청을 만들고 응답을 해석하는 방식을 유지하면서 AI Gateway를 거친다. 기존 코드가 공급사 전용 요청 형식을 사용한다면 단순히 카탈로그 문자열로 치환할 일이 아니다. 모델 객체 연결 문서에서 해당 경로를 확인해야 한다.

AI Search를 함께 쓰던 앱은 별도로 옮긴다. 기존 패키지의 이전 안내는 새 검색 제공자가 ai_search_namespaces 바인딩을 사용한다고 명시한다. 모델 생성과 검색 호출을 한꺼번에 createAI로 바꾸는 방식은 맞지 않는다.

정상 응답 뒤에는 fallback과 연결 중단을 따로 확인한다

새 fallback은 주 모델이 아직 출력을 내지 않은 상태에서 실패하면 다음 모델을 시도한다. 이전 기능을 추적한 공식 이슈의 10월 20일 답변에 따르면 이 전환은 클라이언트에서 이루어진다. 예전 Universal Endpoint의 서버 측 전환과 같은 구현이 아니며, gateway에서 전환하려면 dynamic route 자체의 fallback을 구분해야 한다.

끊긴 답변의 재개도 별도 기능이다. 바인딩으로 호출한 카탈로그 모델과 dynamic route 스트림은 재개할 수 있지만, @cf/ 스트림과 모델 객체에는 같은 재개 기능이 없다. 출력 중간에 모델을 바꿔 답변을 이어 주는 기능으로 이해하면 안 된다.

이전 확인은 현재 앱이 쓰는 모델로 정상 응답을 받은 뒤, 실제 의존하는 실패 경로를 점검하는 순서가 적절하다. 검색 바인딩과 fallback까지 확인했을 때 기존 두 패키지를 제거할 범위가 분명해진다.