clanker25/ai

Ajouter un Package de Fournisseur

Ajouter un package propriétaire complet @ai-sdk/<provider> qui respecte les interfaces de fournisseur actuelles, les conventions du dépôt, les exigences de sécurité et le processus de publication.

Lire les Sources de Vérité Actuelles

Avant d'implémenter quoi que ce soit, lisez :

• Ajouter un nouveau fournisseur pour les exigences actuelles du package et de publication
• Notes de développement des fournisseurs pour la nomenclature, les schémas et la sérialisation des workflows
• Architecture des fournisseurs pour l'abstraction du fournisseur
• Gestion sécurisée des URLs lorsque le fournisseur récupère des URLs de polling, d'image, d'audio, de vidéo ou autres

Utilisez PR #18595 comme exemple récent de bout en bout, mais choisissez le package de fournisseur actuel dont la forme de l'API et les types de modèles ressemblent le plus au nouveau fournisseur comme référence d'implémentation.

Les tiers peuvent publier des packages de fournisseur en dehors de ce dépôt. Un nouveau package propriétaire @ai-sdk/<provider> nécessite une discussion préalable dans une issue. Confirmez qu'un accord existe avant d'implémenter le package.

Découvrir le Contrat API

Avant de concevoir les classes de modèles, recherchez une spécification OpenAPI ou Swagger officielle et versionnée dans la documentation ou les dépôts du fournisseur. Privilégiez les spécifications propriétaires et enregistrez l'URL source ainsi que sa version, sa date de publication ou son commit dans les notes d'implémentation ou la pull request.

Utilisez la spécification et la documentation officielle pour identifier :

• les URLs de base et les schémas d'authentification
• les endpoints supportés, les types de modèles et les capacités
• les paramètres de requête et les formes des réponses
• les transports de streaming et les formats d'événements
• les enveloppes de réponses d'erreur
• les flux de polling asynchrone et de téléchargement d'URL

Considérez une spécification OpenAPI comme une preuve d'implémentation, pas comme une vérité absolue. Les spécifications sont souvent incomplètes pour les événements envoyés par le serveur, les deltas de streaming, le contenu polymorphe, les appels d'outils, les champs nullables et les erreurs. N'ajoutez pas de client généré ou de types de production générés par défaut. Implémentez des types minimaux écrits à la main et des schémas Zod, puis vérifiez-les par rapport à la documentation officielle et aux réponses API capturées.

Si aucune spécification officielle n'existe, dérivez le contrat de la documentation officielle et des fixtures de réponse réelles, et notez cette limitation dans la pull request.

Planifier la Forme du Fournisseur

Déterminez quelles interfaces de modèles du SDK AI le fournisseur supporte, telles que LanguageModelV4, EmbeddingModelV4, ImageModelV4, SpeechModelV4, TranscriptionModelV4, RerankingModelV4, ou Experimental_VideoModelV4.

Avant d'introduire une dépendance, un modèle d'API publique ou une nouvelle abstraction, lisez contributing/decisions/README.md et les ADRs acceptés pertinents. Privilégiez les utilitaires de fournisseur existants et les modèles d'implémentation.

Échafauder le Package

Créez packages/<provider>/ en adaptant un package de fournisseur actuel comparable. Un package typique contient :

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

Respectez les conventions actuelles du package plutôt que de recréer la configuration de mémoire :

• Définissez la version du package du dépôt exactement sur 2.0.0, sans suffixe de pré-version.
• Créez CHANGELOG.md avec un en-tête initial # @ai-sdk/<provider>.
• Utilisez la configuration tsdown partagée et le modèle actuel d'injection de version de package à partir d'un package de fournisseur comparable.
• Étendez ./node_modules/@vercel/ai-tsconfig/ts-library.json, activez un projet composite et ajoutez des références de package pour les dépendances de l'espace de travail.
• Incluez les scripts standard de build, clean, type-check, test Node et test Edge.
• Incluez les métadonnées standard files, documentation prepack, repository, bugs, engines et provenance publique de publication.
• Utilisez workspace:* pour les dépendances de l'espace de travail du SDK AI. Ajoutez @ai-sdk/test-server uniquement lorsque les tests l'utilisent.
• Supportez la plage de dépendances pair Zod 3 et Zod 4 du dépôt et utilisez zod/v4 pour les nouveaux schémas d'implémentation.

Exécutez pnpm update-references après avoir ajouté ou modifié des dépendances de l'espace de travail.

Implémenter la Fabrique de Fournisseur

Suivez le modèle actuel de fabrique de fournisseur :

• Définissez une interface de fournisseur qui étend ProviderV4.
• Exportez create<Provider>(settings) et une instance de fournisseur par défaut.
• Rendez le fournisseur appelable lorsqu'il a un type de modèle par défaut significatif et que les fournisseurs comparables suivent ce modèle ; sinon, retournez un objet fournisseur.
• Définissez provider.specificationVersion = 'v4'.
• Implémentez les méthodes de fabrique entièrement spécifiées requises par ProviderV4, telles que languageModel, embeddingModel et imageModel.
• Ajoutez des alias courts tels que chat, embedding ou image uniquement lorsqu'ils améliorent l'API du fournisseur.
• Lancez NoSuchModelError à partir des fabriques de modèles obligatoires non supportés.
• Supportez les paramètres appropriés au fournisseur tels que apiKey, baseURL, headers et une implémentation personnalisée de fetch.
• Chargez les identifiants avec loadApiKey ou l'utilitaire partagé approprié, normalisez les URLs de base configurables et incluez la version du package dans le suffixe du user-agent.
• Exportez la fabrique de fournisseur, l'instance par défaut, les types d'options publiques, les types d'ID de modèle et VERSION depuis src/index.ts.

Implémenter les Classes de Modèles

Implémentez chaque modèle supporté en utilisant l'interface appropriée de @ai-sdk/provider et les utilitaires partagés de @ai-sdk/provider-utils.

Les types et schémas d'options du fournisseur doivent suivre les règles de nomenclature et d'exportation du dépôt. Les champs d'options destinés à l'utilisateur doivent utiliser .optional() sauf si null est significatif. Les schémas de réponse doivent être minimaux, tolérer les champs de fournisseur inutilisés et utiliser .nullish() là où l'API peut omettre ou retourner null.

Toutes les classes de modèles doivent implémenter le contrat de sérialisation de workflow décrit dans Notes de développement des fournisseurs :

• rendre les en-têtes de configuration du modèle optionnels
• ajouter les méthodes statiques WORKFLOW_SERIALIZE et WORKFLOW_DESERIALIZE
• utiliser serializeModel, serializeModelOptions ou le modèle existant correspondant
• s'assurer que l'authentification et les autres fonctions non sérialisables peuvent être restaurées à partir des options de requête ou de l'environnement de workflow

Gérer les Réponses, les Erreurs et les URLs en Toute Sécurité

• N'utilisez jamais JSON.parse dans le code de production. Utilisez parseJSON ou safeParseJSON de @ai-sdk/provider-utils.
• Validez les réponses réussies et échouées avec des schémas minimaux et des gestionnaires de réponse partagés tels que createJsonResponseHandler et createJsonErrorResponseHandler.
• Introduisez une sous-classe AISDKError personnalisée uniquement lorsque le package a besoin d'un nouveau type d'erreur SDK public ; les échecs HTTP ordinaires du fournisseur doivent utiliser la gestion d'erreur API partagée.
• Définissez validateUrl explicitement sur chaque appel getFromApi.
• Utilisez validateUrl: true lorsque l'hôte ou le schéma de l'URL provient d'une réponse du fournisseur, et false lorsqu'il est dérivé d'une URL de base configurée par le développeur.
• Utilisez trustedOrigin pour les URLs de réponse légitimes qui peuvent pointer vers un endpoint privé ou auto-hébergé configuré.
• Utilisez credentialedOrigin lorsque des identifiants peuvent être envoyés sur le premier saut, afin qu'ils soient retenus des URLs hors origine et des redirections.

Lisez Gestion sécurisée des URLs avant d'implémenter tout flux de polling ou de téléchargement d'URL fourni par le fournisseur.

Tester Contre le Contrat Réel

Ajoutez des tests ciblés pour :

• les valeurs par défaut du fournisseur, les paramètres personnalisés, les alias de fabrique et les types de modèles non supportés
• la sérialisation des requêtes et l'analyse des réponses
• les événements de streaming, l'utilisation, les raisons de fin, les avertissements, les appels d'outils et les métadonnées du fournisseur lorsque supportés
• l'analyse des réponses d'erreur et les réponses malformées
• la sérialisation et la désérialisation du workflow
• les décisions de confiance d'URL pour le polling ou les téléchargements
• les environnements d'exécution Node.js et Edge

Utilisez des réponses réelles du fournisseur comme fixtures lorsque c'est pratique. Lisez le skill de capture de fixture de réponse API avant de les capturer. Réduisez les fixtures surdimensionnées uniquement lorsque cela ne change pas leur sémantique.

Ajouter des Exemples et l'Intégration au Dépôt

Lisez le skill d'exemple AI Functions avant d'ajouter des exemples.

Pour chaque type de modèle supporté, placez l'exemple d'entrée à :

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

Placez des exemples supplémentaires dans le même répertoire de fournisseur avec des noms descriptifs en kebab-case.ts. Ne créez pas de fichiers de fournisseur plats tels que src/generate-text/<provider>.ts.

Mettez également à jour les points d'intégration pertinents du dépôt :

• ajoutez @ai-sdk/<provider> à examples/ai-functions/package.json
• ajoutez sa référence de projet à examples/ai-functions/tsconfig.json
• ajoutez les identifiants requis à examples/ai-functions/.env.example
• ajoutez les noms d'identifiants à la configuration d'environnement racine turbo.json si nécessaire
• exécutez pnpm update-references pour mettre à jour les références TypeScript racine et du package

Exécutez des exemples représentatifs contre l'API réelle et confirmez le comportement non-streaming et streaming lorsque supporté.

Ajouter la Documentation du Package et du Fournisseur

• Rédigez le README.md du package avec l'installation, l'authentification, la configuration, les modèles supportés et l'utilisation de base.
• Ajoutez content/providers/01-ai-sdk-providers/<last number + 10>-<provider>.mdx avec la configuration, les capacités du modèle, les options du fournisseur et des exemples.
• Configurez le script de prepack de documentation du package pour inclure cette page de fournisseur.

Préparer la Publication

Créez un changeset majeur pour le nouveau package de fournisseur. Le package du dépôt reste à 2.0.0 simple ; n'ajoutez pas de suffixe -beta, -canary ou autre pré-version.

Avant la première publication automatisée, coordonnez-vous avec l'équipe IT de Vercel pour amorcer un package @ai-sdk/<provider> vide sur npm à 0.0.0 et configurez son Trusted Publisher. Suivez Amorçage d'un nouveau package @ai-sdk/*. La version d'amorçage npm temporaire est distincte de la version du package du dépôt.

Lorsque main est en mode pré-version, ne rétroportez pas le nouveau package vers une branche stable vX.Y.

Vérifier le Changement Complet

Exécutez, au minimum :

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

Exécutez également les nouveaux exemples avec les identifiants de fournisseur requis. Exécutez le build racine lorsque les modifications apportées aux packages partagés ou à la configuration de build le rendent pertinent.

Checklist de Complétion

• Package propriétaire approuvé dans une issue
• Spécification OpenAPI officielle examinée, ou son absence documentée
• Spécification API vérifiée par rapport à la documentation et aux réponses réelles
• Implémentation de fournisseur actuelle comparable sélectionnée
• Package du dépôt créé à la version 2.0.0
• Configuration du package, TypeScript, build, test, provenance et documentation ajoutée
• La fabrique de fournisseur implémente ProviderV4
• Classes de modèles supportées et types d'options publiques implémentés
• Sérialisation de workflow implémentée pour chaque classe de modèle
• Analyse des réponses, gestion des erreurs et récupération d'URL suivent les règles de sécurité du dépôt
• Les tests Node et Edge passent avec des fixtures de réponse représentatives
• Exemples AI Functions imbriqués ajoutés et exécutés avec succès
• Dépendances d'exemple, références TypeScript, variables d'environnement et configuration Turbo mis à jour
• README et documentation du fournisseur ajoutés
• Changeset majeur ajouté
• Package npm et amorçage Trusted Publisher coordonnés
• Build du package, tests, vérification complète des types et vérifications du dépôt réussis