클랭커25/ai

제공업체 패키지 추가하기

현재 제공업체 인터페이스, 리포지토리 규칙, 보안 요구 사항 및 릴리스 프로세스를 따르는 완전한 퍼스트파티 @ai-sdk/<provider> 패키지를 추가합니다.

현재 소스 오브 트루스 읽기

구현하기 전에 다음을 읽으십시오:

• 새 제공업체 추가 - 현재 패키지 및 릴리스 요구 사항 확인
• 제공업체 개발 노트 - 명명 규칙, 스키마, 워크플로 직렬화 확인
• 제공업체 아키텍처 - 제공업체 추상화 확인
• 안전한 URL 처리 - 제공업체가 폴링, 이미지, 오디오, 비디오 또는 기타 URL을 가져올 때

최근 종단간 예제로 PR #18595를 참조하되, API 형태와 모델 유형이 새 제공업체와 가장 유사한 현재 제공업체 패키지를 구현 참조로 선택하십시오.

서드파티는 이 리포지토리 외부에 제공업체 패키지를 게시할 수 있습니다. 새로운 퍼스트파티 @ai-sdk/<provider> 패키지는 이슈에서 사전 논의가 필요합니다. 패키지를 구현하기 전에 해당 동의가 존재하는지 확인하십시오.

API 계약 발견하기

모델 클래스를 설계하기 전에, 제공업체의 문서나 리포지토리에서 공식 버전 관리된 OpenAPI 또는 Swagger 명세를 찾으십시오. 퍼스트파티 명세를 선호하며, 소스 URL과 함께 버전, 게시 날짜 또는 커밋을 구현 노트나 풀 리퀘스트에 기록하십시오.

명세와 공식 문서를 사용하여 다음을 식별하십시오:

• 기본 URL 및 인증 체계
• 지원되는 엔드포인트, 모델 유형 및 기능
• 요청 매개변수 및 응답 형태
• 스트리밍 전송 및 이벤트 형식
• 오류 응답 구조
• 비동기 폴링 및 다운로드 URL 흐름

OpenAPI 명세를 구현 증거로 취급하되, 절대적으로 신뢰하지는 마십시오. 명세는 서버 전송 이벤트, 스트리밍 델타, 다형성 콘텐츠, 도구 호출, nullable 필드 및 오류에 대해 종종 불완전합니다. 생성된 클라이언트나 프로덕션 유형을 기본적으로 추가하지 마십시오. 최소한의 수동 작성 타입과 Zod 스키마를 구현한 다음, 공식 문서와 캡처된 API 응답에 대해 검증하십시오.

공식 명세가 없는 경우, 공식 문서와 실제 응답 픽스처에서 계약을 도출하고 해당 제한 사항을 풀 리퀘스트에 명시하십시오.

제공업체 형태 계획하기

제공업체가 지원하는 AI SDK 모델 인터페이스(LanguageModelV4, EmbeddingModelV4, ImageModelV4, SpeechModelV4, TranscriptionModelV4, RerankingModelV4 또는 Experimental_VideoModelV4)를 결정하십시오.

의존성, 공개 API 패턴 또는 새로운 추상화를 도입하기 전에 contributing/decisions/README.md 및 관련 수용된 ADR을 읽으십시오. 기존 제공업체 유틸리티와 구현 패턴을 선호하십시오.

패키지 스캐폴딩하기

현재 비교 가능한 제공업체 패키지를 적용하여 packages/<provider>/를 생성하십시오. 일반적인 패키지에는 다음이 포함됩니다:

packages/<provider>/
├── src/
│   ├── index.ts
│   ├── version.ts
│   ├── <provider>-provider.ts
│   ├── <provider>-provider.test.ts
│   ├── <provider>-<model-type>-model.ts
│   ├── <provider>-<model-type>-model.test.ts
│   └── <provider>-<model-type>-options.ts
├── CHANGELOG.md
├── README.md
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── tsdown.config.ts
├── turbo.json
├── vitest.node.config.js
└── vitest.edge.config.js

메모리에서 구성을 재현하지 말고 현재 패키지 규칙을 유지하십시오:

• 리포지토리 패키지 버전을 정확히 2.0.0으로 설정하고, 프리릴리스 접미사를 붙이지 마십시오.
• # @ai-sdk/<provider> 제목으로 CHANGELOG.md를 생성하십시오.
• 공유 tsdown 구성과 비교 가능한 제공업체 패키지의 현재 패키지 버전 주입 패턴을 사용하십시오.
• ./node_modules/@vercel/ai-tsconfig/ts-library.json을 확장하고, 복합 프로젝트를 활성화하며, 워크스페이스 의존성에 대한 패키지 참조를 추가하십시오.
• 표준 빌드, 정리, 타입 검사, Node 테스트 및 Edge 테스트 스크립트를 포함하십시오.
• 표준 files, 문서 프리팩, 리포지토리, 버그, 엔진 및 공개 출처 증명 게시 메타데이터를 포함하십시오.
• AI SDK 워크스페이스 의존성에는 workspace:*를 사용하십시오. @ai-sdk/test-server는 테스트에서 사용할 때만 추가하십시오.
• 리포지토리의 Zod 3 및 Zod 4 피어 의존성 범위를 지원하고, 새로운 구현 스키마에는 zod/v4를 사용하십시오.

워크스페이스 의존성을 추가하거나 변경한 후 pnpm update-references를 실행하십시오.

제공업체 팩토리 구현하기

현재 제공업체 팩토리 패턴을 따르십시오:

• ProviderV4를 확장하는 제공업체 인터페이스를 정의하십시오.
• create<Provider>(settings)와 기본 제공업체 인스턴스를 내보내십시오.
• 의미 있는 기본 모델 유형이 있고 비교 가능한 제공업체가 해당 패턴을 따르는 경우 제공업체를 호출 가능하게 만드십시오. 그렇지 않으면 제공업체 객체를 반환하십시오.
• provider.specificationVersion = 'v4'를 설정하십시오.
• ProviderV4에 필요한 완전히 명시된 팩토리 메서드(languageModel, embeddingModel, imageModel 등)를 구현하십시오.
• 제공업체의 API를 개선하는 경우에만 chat, embedding 또는 image와 같은 짧은 별칭을 추가하십시오.
• 지원되지 않는 필수 모델 팩토리에서 NoSuchModelError를 던지십시오.
• apiKey, baseURL, headers 및 사용자 정의 fetch 구현과 같은 제공업체에 적합한 설정을 지원하십시오.
• loadApiKey 또는 적절한 공유 유틸리티를 사용하여 자격 증명을 로드하고, 구성 가능한 기본 URL을 정규화하며, 사용자 에이전트 접미사에 패키지 버전을 포함하십시오.
• src/index.ts에서 제공업체 팩토리, 기본 인스턴스, 공개 옵션 타입, 모델 ID 타입 및 VERSION을 내보내십시오.

모델 클래스 구현하기

@ai-sdk/provider의 적절한 인터페이스와 @ai-sdk/provider-utils의 공유 유틸리티를 사용하여 지원되는 각 모델을 구현하십시오.

제공업체 옵션 타입과 스키마는 리포지토리 명명 및 내보내기 규칙을 따라야 합니다. 사용자에게 노출되는 옵션 필드는 null이 의미 있는 경우가 아니라면 .optional()을 사용해야 합니다. 응답 스키마는 최소화하고, 사용되지 않는 제공업체 필드를 허용하며, API가 필드를 생략하거나 null을 반환할 수 있는 경우 .nullish()를 사용하십시오.

모든 모델 클래스는 제공업체 개발 노트에 설명된 워크플로 직렬화 계약을 구현해야 합니다:

• 모델 구성 헤더를 선택 사항으로 만드십시오.
• WORKFLOW_SERIALIZE 및 WORKFLOW_DESERIALIZE 정적 메서드를 추가하십시오.
• serializeModel, serializeModelOptions 또는 일치하는 기존 패턴을 사용하십시오.
• 인증 및 기타 직렬화 불가능한 함수가 요청 옵션이나 워크플로 환경에서 복원될 수 있는지 확인하십시오.

응답, 오류 및 URL 안전하게 처리하기

• 프로덕션 코드에서 JSON.parse를 절대 사용하지 마십시오. @ai-sdk/provider-utils의 parseJSON 또는 safeParseJSON을 사용하십시오.
• 최소 스키마와 createJsonResponseHandler 및 createJsonErrorResponseHandler와 같은 공유 응답 핸들러를 사용하여 성공 및 실패 응답을 검증하십시오.
• 패키지에 새로운 공개 SDK 오류 타입이 필요한 경우에만 사용자 정의 AISDKError 서브클래스를 도입하십시오. 일반적인 제공업체 HTTP 실패는 공유 API 오류 처리를 사용해야 합니다.
• 모든 getFromApi 호출에 validateUrl을 명시적으로 설정하십시오.
• URL 호스트나 체계가 제공업체 응답에서 오는 경우 validateUrl: true를 사용하고, 개발자 구성 기본 URL에서 파생된 경우 false를 사용하십시오.
• 구성된 비공개 또는 자체 호스팅 엔드포인트를 가리킬 수 있는 합법적인 응답 URL에는 trustedOrigin을 사용하십시오.
• 첫 번째 홉에서 자격 증명이 전송될 수 있는 경우 credentialedOrigin을 사용하여, 오리진 외부 URL 및 리디렉션으로 자격 증명이 전송되지 않도록 하십시오.

폴링 또는 제공업체 제공 다운로드 URL 흐름을 구현하기 전에 안전한 URL 처리를 읽으십시오.

실제 계약에 대해 테스트하기

다음에 대한 집중 테스트를 추가하십시오:

• 제공업체 기본값, 사용자 정의 설정, 팩토리 별칭 및 지원되지 않는 모델 유형
• 요청 직렬화 및 응답 파싱
• 스트리밍 이벤트, 사용량, 완료 이유, 경고, 도구 호출 및 제공업체 메타데이터(지원되는 경우)
• 오류 응답 파싱 및 잘못된 응답
• 워크플로 직렬화 및 역직렬화
• 폴링 또는 다운로드를 위한 URL 신뢰 결정
• Node.js 및 Edge 런타임 모두

가능하면 실제 제공업체 응답을 픽스처로 사용하십시오. 픽스처를 캡처하기 전에 API 응답 픽스처 캡처 스킬을 읽으십시오. 과도하게 큰 픽스처는 의미를 변경하지 않는 경우에만 자르십시오.

예제 및 리포지토리 통합 추가하기

예제를 추가하기 전에 AI 함수 예제 스킬을 읽으십시오.

지원되는 각 모델 유형에 대해 항목 예제를 다음 위치에 배치하십시오:

examples/ai-functions/src/<function>/<provider>/basic.ts

추가 예제는 동일한 제공업체 디렉토리에 설명적인 kebab-case.ts 이름으로 배치하십시오. src/generate-text/<provider>.ts와 같은 평면 제공업체 파일을 생성하지 마십시오.

또한 관련 리포지토리 통합 지점을 업데이트하십시오:

• examples/ai-functions/package.json에 @ai-sdk/<provider>를 추가하십시오.
• examples/ai-functions/tsconfig.json에 프로젝트 참조를 추가하십시오.
• examples/ai-functions/.env.example에 필요한 자격 증명을 추가하십시오.
• 필요할 때 루트 turbo.json 환경 구성에 자격 증명 이름을 추가하십시오.
• pnpm update-references를 실행하여 루트 및 패키지 TypeScript 참조를 업데이트하십시오.

대표적인 예제를 실제 API에 대해 실행하고, 지원되는 경우 비스트리밍 및 스트리밍 동작을 모두 확인하십시오.

패키지 및 제공업체 문서 추가하기

• 설치, 인증, 구성, 지원되는 모델 및 기본 사용법이 포함된 패키지 README.md를 작성하십시오.
• 설정, 모델 기능, 제공업체 옵션 및 예제가 포함된 content/providers/01-ai-sdk-providers/<last number + 10>-<provider>.mdx를 추가하십시오.
• 패키지의 문서 프리팩 스크립트가 해당 제공업체 페이지를 포함하도록 구성하십시오.

릴리스 준비하기

새 제공업체 패키지에 대한 주요 체인지셋을 생성하십시오. 리포지토리 패키지는 일반 2.0.0으로 유지됩니다. -beta, -canary 또는 다른 프리릴리스 접미사를 추가하지 마십시오.

첫 번째 자동화된 릴리스 전에 Vercel IT 팀과 협력하여 npm에 0.0.0으로 빈 @ai-sdk/<provider> 패키지를 부트스트랩하고 Trusted Publisher를 구성하십시오. 새 @ai-sdk/* 패키지 부트스트래핑을 따르십시오. 임시 npm 부트스트랩 버전은 리포지토리 패키지 버전과 별개입니다.

main이 프리릴리스 모드에 있을 때, 새 패키지를 안정적인 vX.Y 브랜치로 백포트하지 마십시오.

전체 변경 사항 확인하기

최소한 다음을 실행하십시오:

pnpm --filter @ai-sdk/<provider> build
pnpm --filter @ai-sdk/<provider> test
pnpm --filter @ai-sdk/<provider> type-check
pnpm type-check:full
pnpm check

또한 필요한 제공업체 자격 증명을 사용하여 새 예제를 실행하십시오. 공유 패키지나 빌드 구성의 변경 사항이 관련될 때 루트 빌드를 실행하십시오.

완료 체크리스트

• 이슈에서 퍼스트파티 패키지 승인됨
• 공식 OpenAPI 명세 검토됨, 또는 부재가 문서화됨
• API 명세가 문서 및 실제 응답과 비교 확인됨
• 비교 가능한 현재 제공업체 구현 선택됨
• 버전 2.0.0으로 리포지토리 패키지 생성됨
• 패키지, TypeScript, 빌드, 테스트, 출처 증명 및 문서 구성 추가됨
• 제공업체 팩토리가 ProviderV4 구현
• 지원되는 모델 클래스 및 공개 옵션 타입 구현됨
• 모든 모델 클래스에 대한 워크플로 직렬화 구현됨
• 응답 파싱, 오류 처리 및 URL 가져오기가 리포지토리 보안 규칙을 따름
• Node 및 Edge 테스트가 대표적인 응답 픽스처로 통과함
• 중첩된 AI 함수 예제가 추가되고 성공적으로 실행됨
• 예제 의존성, TypeScript 참조, 환경 변수 및 Turbo 구성 업데이트됨
• README 및 제공업체 문서 추가됨
• 주요 체인지셋 추가됨
• npm 패키지 및 Trusted Publisher 부트스트래핑 조정됨
• 패키지 빌드, 테스트, 전체 타입 검사 및 리포지토리 검사 통과