Ein Provider-Paket hinzufügen

Fügen Sie ein vollständiges First-Party @ai-sdk/<provider> Paket hinzu, das den aktuellen Provider-Schnittstellen, Repository-Konventionen, Sicherheitsanforderungen und dem Freigabeprozess folgt.

Aktuelle Quellen der Wahrheit lesen

Lesen Sie vor der Implementierung:

Neuen Provider hinzufügen für aktuelle Paket- und Freigabeanforderungen
Provider-Entwicklungshinweise für Namensgebung, Schemas und Workflow-Serialisierung
Provider-Architektur für die Provider-Abstraktion
Sichere URL-Handhabung wenn der Provider Polling, Bild-, Audio-, Video- oder andere URLs abruft

Verwenden Sie PR #18595 als aktuelles End-to-End-Beispiel, wählen Sie aber das aktuelle Provider-Paket, dessen API-Form und Modelltypen dem neuen Provider am ähnlichsten sind, als Implementierungsreferenz.

Drittanbieter können Provider-Pakete außerhalb dieses Repositorys veröffentlichen. Ein neues First-Party @ai-sdk/<provider> Paket erfordert eine vorherige Diskussion in einem Issue. Bestätigen Sie, dass die Zustimmung vor der Implementierung des Pakets vorliegt.

Den API-Vertrag entdecken

Bevor Sie Modellklassen entwerfen, suchen Sie nach einer offiziellen, versionierten OpenAPI- oder Swagger-Spezifikation in der Dokumentation oder den Repositorys des Providers. Bevorzugen Sie First-Party-Spezifikationen und notieren Sie die Quell-URL sowie deren Version, Veröffentlichungsdatum oder Commit in den Implementierungsnotizen oder im Pull-Request.

Verwenden Sie die Spezifikation und offizielle Dokumentation, um Folgendes zu identifizieren:

Basis-URLs und Authentifizierungsschemata
unterstützte Endpunkte, Modelltypen und Fähigkeiten
Anforderungsparameter und Antwortformen
Streaming-Transports und Ereignisformate
Fehlerantwort-Envelopes
asynchrone Polling- und Download-URL-Flows

Behandeln Sie eine OpenAPI-Spezifikation als Implementierungsnachweis, nicht als unbestrittene Wahrheit. Spezifikationen sind oft unvollständig für Server-Sent Events, Streaming-Deltas, polymorphe Inhalte, Tool Calls, nullable Felder und Fehler. Fügen Sie standardmäßig keinen generierten Client oder generierte Produktionstypen hinzu. Implementieren Sie minimale handgeschriebene Types und Zod-Schemas und überprüfen Sie sie dann anhand der offiziellen Dokumentation und erfasster API-Antworten.

Wenn keine offizielle Spezifikation existiert, leiten Sie den Vertrag aus offizieller Dokumentation und echten Antwort-Fixtures ab und vermerken Sie diese Einschränkung im Pull-Request.

Die Provider-Form planen

Bestimmen Sie, welche AI SDK-Modellschnittstellen der Provider unterstützt, wie LanguageModelV4, EmbeddingModelV4, ImageModelV4, SpeechModelV4, TranscriptionModelV4, RerankingModelV4 oder Experimental_VideoModelV4.

Lesen Sie vor der Einführung einer Abhängigkeit, eines öffentlichen API-Musters oder einer neuen Abstraktion contributing/decisions/README.md und relevante akzeptierte ADRs. Bevorzugen Sie vorhandene Provider-Hilfsprogramme und Implementierungsmuster.

Das Paket strukturieren

Erstellen Sie packages/<provider>/, indem Sie ein aktuelles, vergleichbares Provider-Paket anpassen. Ein typisches Paket enthält:

packages/<provider>/
├── src/
│   ├── index.ts
│   ├── version.ts
│   ├── <provider>-provider.ts
│   ├── <provider>-provider.test.ts
│   ├── <provider>-<modelltyp>-model.ts
│   ├── <provider>-<modelltyp>-model.test.ts
│   └── <provider>-<modelltyp>-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

Behalten Sie aktuelle Paketkonventionen bei, anstatt die Konfiguration aus dem Gedächtnis neu zu erstellen:

Setzen Sie die Repository-Paketversion auf exakt 2.0.0, ohne Präfix für Vorabversionen.
Erstellen Sie CHANGELOG.md mit einer anfänglichen Überschrift # @ai-sdk/<provider>.
Verwenden Sie die gemeinsame tsdown-Konfiguration und das aktuelle Muster zur Paketversion-Injektion aus einem vergleichbaren Provider-Paket.
Erweitern Sie ./node_modules/@vercel/ai-tsconfig/ts-library.json, aktivieren Sie ein Composite-Projekt und fügen Sie Paketreferenzen für Workspace-Abhängigkeiten hinzu.
Fügen Sie die standardmäßigen Build-, Clean-, Type-Check-, Node-Test- und Edge-Test-Skripte hinzu.
Fügen Sie die standardmäßigen Metadaten files, documentation prepack, repository, bugs, engines und public provenance publishing hinzu.
Verwenden Sie workspace:* für AI SDK-Workspace-Abhängigkeiten. Fügen Sie @ai-sdk/test-server nur hinzu, wenn Tests es verwenden.
Unterstützen Sie den Bereich der Peer-Abhängigkeiten des Repositorys für Zod 3 und Zod 4 und verwenden Sie zod/v4 für neue Implementierungsschemas.

Führen Sie pnpm update-references aus, nachdem Sie Workspace-Abhängigkeiten hinzugefügt oder geändert haben.

Die Provider-Factory implementieren

Befolgen Sie das aktuelle Provider-Factory-Muster:

Definieren Sie ein Provider-Interface, das ProviderV4 erweitert.
Exportieren Sie create<Provider>(settings) und eine Standard-Provider-Instanz.
Machen Sie den Provider aufrufbar, wenn er einen sinnvollen Standard-Modelltyp hat und vergleichbare Provider diesem Muster folgen; andernfalls geben Sie ein Provider-Objekt zurück.
Setzen Sie provider.specificationVersion = 'v4'.
Implementieren Sie die vollständig spezifizierten Factory-Methoden, die von ProviderV4 benötigt werden, wie languageModel, embeddingModel und imageModel.
Fügen Sie kurze Aliase wie chat, embedding oder image nur hinzu, wenn sie die API des Providers verbessern.
Werfen Sie NoSuchModelError aus nicht unterstützten erforderlichen Modell-Factories.
Unterstützen Sie providerangepasste Einstellungen wie apiKey, baseURL, headers und eine benutzerdefinierte fetch-Implementierung.
Laden Sie Anmeldeinformationen mit loadApiKey oder dem entsprechenden gemeinsamen Hilfsprogramm, normalisieren Sie konfigurierbare Basis-URLs und fügen Sie die Paketversion in das User-Agent-Suffix ein.
Exportieren Sie die Provider-Factory, die Standardinstanz, öffentliche Optionstypen, Modell-ID-Typen und VERSION aus src/index.ts.

Modellklassen implementieren

Implementieren Sie jedes unterstützte Modell mit der entsprechenden Schnittstelle aus @ai-sdk/provider und gemeinsamen Hilfsprogrammen aus @ai-sdk/provider-utils.

Provider-Optionstypen und -Schemas müssen den Repository-Namens- und Exportregeln folgen. Benutzerseitige Optionsfelder sollten .optional() verwenden, es sei denn, null ist sinnvoll. Antwortschemas sollten minimal sein, ungenutzte Provider-Felder tolerieren und .nullish() verwenden, wo die API möglicherweise Werte auslässt oder null zurückgibt.

Alle Modellklassen müssen den in Provider-Entwicklungshinweisen beschriebenen Workflow-Serialisierungsvertrag implementieren:

machen Sie Modellkonfigurations-Header optional
fügen Sie statische Methoden WORKFLOW_SERIALIZE und WORKFLOW_DESERIALIZE hinzu
verwenden Sie serializeModel, serializeModelOptions oder das passende vorhandene Muster
stellen Sie sicher, dass Authentifizierung und andere nicht serialisierbare Funktionen aus Anfrageoptionen oder der Workflow-Umgebung wiederhergestellt werden können

Antworten, Fehler und URLs sicher behandeln

Verwenden Sie niemals JSON.parse im Produktionscode. Verwenden Sie parseJSON oder safeParseJSON aus @ai-sdk/provider-utils.
Validieren Sie erfolgreiche und fehlgeschlagene Antworten mit minimalen Schemas und gemeinsamen Antwort-Handlern wie createJsonResponseHandler und createJsonErrorResponseHandler.
Führen Sie eine benutzerdefinierte AISDKError-Unterklasse nur ein, wenn das Paket einen neuen öffentlichen SDK-Fehlertyp benötigt; gewöhnliche Provider-HTTP-Fehler sollten die gemeinsame API-Fehlerbehandlung verwenden.
Setzen Sie validateUrl explizit bei jedem getFromApi-Aufruf.
Verwenden Sie validateUrl: true, wenn der URL-Host oder das Schema aus einer Provider-Antwort stammt, und false, wenn es von einer entwicklerkonfigurierten Basis-URL abgeleitet ist.
Verwenden Sie trustedOrigin für legitime Antwort-URLs, die auf einen konfigurierten privaten oder selbst gehosteten Endpunkt verweisen können.
Verwenden Sie credentialedOrigin, wenn Anmeldeinformationen beim ersten Hop gesendet werden können, damit sie von Off-Origin-URLs und Weiterleitungen zurückgehalten werden.

Lesen Sie Sichere URL-Handhabung vor der Implementierung eines Polling- oder vom Provider bereitgestellten Download-URL-Flows.

Gegen den echten Vertrag testen

Fügen Sie fokussierte Tests hinzu für:

Provider-Standardwerte, benutzerdefinierte Einstellungen, Factory-Aliase und nicht unterstützte Modelltypen
Anforderungsserialisierung und Antwortanalyse
Streaming-Ereignisse, Nutzung, Abschlussgründe, Warnungen, Tool Calls und Provider-Metadaten, wo unterstützt
Fehlerantwortanalyse und fehlerhafte Antworten
Workflow-Serialisierung und -Deserialisierung
URL-Vertrauensentscheidungen für Polling oder Downloads
sowohl Node.js- als auch Edge-Laufzeitumgebungen

Verwenden Sie echte Provider-Antworten als Fixtures, wenn praktikabel. Lesen Sie die Erfassen von API-Antwort-Fixture-Fähigkeit, bevor Sie sie erfassen. Kürzen Sie überdimensionierte Fixtures nur, wenn dies ihre Semantik nicht ändert.

Beispiele und Repository-Integration hinzufügen

Lesen Sie die AI Functions Beispiel-Fähigkeit vor dem Hinzufügen von Beispielen.

Für jeden unterstützten Modelltyp platzieren Sie das Einstiegsbeispiel unter:

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

Platzieren Sie zusätzliche Beispiele im selben Provider-Verzeichnis mit beschreibenden Namen in kebab-case.ts. Erstellen Sie keine flachen Provider-Dateien wie src/generate-text/<provider>.ts.

Aktualisieren Sie auch die relevanten Repository-Integrationspunkte:

fügen Sie @ai-sdk/<provider> zu examples/ai-functions/package.json hinzu
fügen Sie seine Projektreferenz zu examples/ai-functions/tsconfig.json hinzu
fügen Sie erforderliche Anmeldeinformationen zu examples/ai-functions/.env.example hinzu
fügen Sie Anmeldeinformationsnamen zur Wurzel turbo.json Umgebungskonfiguration hinzu, falls erforderlich
führen Sie pnpm update-references aus, um Wurzel- und Paket-TypeScript-Referenzen zu aktualisieren

Führen Sie repräsentative Beispiele gegen die echte API aus und bestätigen Sie sowohl Nicht-Streaming- als auch Streaming-Verhalten, wenn unterstützt.

Paket- und Provider-Dokumentation hinzufügen

Schreiben Sie die Paket-README.md mit Installation, Authentifizierung, Konfiguration, unterstützten Modellen und grundlegender Verwendung.
Fügen Sie content/providers/01-ai-sdk-providers/<letzte nummer + 10>-<provider>.mdx mit Einrichtung, Modellfähigkeiten, Provider-Optionen und Beispielen hinzu.
Konfigurieren Sie das Dokumentations-Prepack-Skript des Pakets, um diese Provider-Seite einzuschließen.

Die Freigabe vorbereiten

Erstellen Sie einen Major-Änderungssatz für das neue Provider-Paket. Das Repository-Paket bleibt bei einfachem 2.0.0; fügen Sie kein -beta, -canary oder ein anderes Präfix für Vorabversionen hinzu.

Koordinieren Sie vor der ersten automatischen Freigabe mit dem Vercel IT-Team, um ein leeres @ai-sdk/<provider> Paket auf npm bei 0.0.0 zu bootstrappen und dessen Trusted Publisher zu konfigurieren. Befolgen Sie Bootstrapping eines neuen @ai-sdk/* Pakets. Die temporäre npm-Bootstrap-Version ist von der Repository-Paketversion getrennt.

Wenn main im Prerelease-Modus ist, portieren Sie das neue Paket nicht zurück in einen stabilen vX.Y Branch.

Die vollständige Änderung überprüfen

Führen Sie mindestens aus:

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

Führen Sie auch die neuen Beispiele mit den erforderlichen Provider-Anmeldeinformationen aus. Führen Sie den Root-Build aus, wenn Änderungen an gemeinsamen Paketen oder der Build-Konfiguration dies relevant machen.

clanker25/ai

Was ist ai?

In Ihrer bevorzugten KI fragen

Dokumentation

Ein Provider-Paket hinzufügen

Aktuelle Quellen der Wahrheit lesen

Den API-Vertrag entdecken

Die Provider-Form planen

Das Paket strukturieren

Die Provider-Factory implementieren

Modellklassen implementieren

Antworten, Fehler und URLs sicher behandeln

Gegen den echten Vertrag testen

Beispiele und Repository-Integration hinzufügen

Paket- und Provider-Dokumentation hinzufügen

Die Freigabe vorbereiten

Die vollständige Änderung überprüfen

Abschluss-Checkliste

Individual skills in this repo

clanker25/ai

clanker25/ai

clanker25/ai

Verwandte Skills

steipete/bluebubbles

steipete/eightctl

steipete/blucli

steipete/bear-notes

steipete/camsnap

steipete/gifgrep