Configuration de l'API de l'agent de codage pi

Le mécanisme officiel Custom Models de pi charge les passerelles et les modèles personnalisés de ~/.pi/agent/models.json. TokenHub utilise le type openai-completions API. Il n'y a pas de formulaire générique « Ajouter un fournisseur » ici ; ce fichier de configuration est le point d'entrée pris en charge.

Étape 1 : préparer un identifiant pour models.json

Dans le même terminal qui lance pi, définissez :

export TOKENHUB_API_KEY="sk-..."

Dans models.json, la valeur doit être "$TOKENHUB_API_KEY" pour lire une variable d'environnement. La documentation de pi indique qu'une chaîne majuscule sans Dans models.json, la valeur doit être "$TOKENHUB_API_KEY"` pour lire une variable d'environnement. La documentation de pi indique qu'une chaîne majuscule sans est traitée comme une clé littérale et non comme un nom de variable d'environnement.

Étape 2 : modifier ~/.pi/agent/models.json

{
  "providers": {
    "tokenhub": {
      "baseUrl": "__API_BASE_URL__/v1",
      "api": "openai-completions",
      "apiKey": "$TOKENHUB_API_KEY",
      "models": [
        {
          "id": "YOUR_TOKENHUB_MODEL_ID",
          "name": "TokenHub / YOUR_TOKENHUB_MODEL_ID",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 8192
        }
      ]
    }
  }
}

Corrigez chaque champ de la page du modèle TokenHub :

• id est l’ID de modèle envoyé au API et est obligatoire.
• Définissez reasoning sur true uniquement pour un modèle prenant en charge le raisonnement étendu.
• input est par défaut du texte. Utilisez ["text", "image"] uniquement pour un modèle avec entrée d'image.
• Bien que contextWindow ait une valeur par défaut, déclarez la fenêtre contextuelle réelle du modèle.
• maxTokens correspond à la sortie maximale, pas à la fenêtre contextuelle.

TokenHub utilise un jeton Bearer. Si votre version pi n’ajoute pas automatiquement l’en-tête Authorization, ajoutez "authHeader": true au niveau du fournisseur.

Étape 3 : ouvrez /model pour recharger le fichier

Exécutez /model dans une session pi. pi recharge models.json à chaque fois que /model s'ouvre, aucun redémarrage n'est donc requis. Choisissez tokenhub/YOUR_TOKENHUB_MODEL_ID, demandez-lui d'expliquer un fichier et testez l'appel de l'outil seulement après que cela réussisse.

Si le fournisseur et le modèle sont affichés mais ne peuvent pas être sélectionnés, le fichier est chargé mais les informations d'identification n'ont pas été résolues. Vérifiez la variable d'environnement ou enregistrez la clé du fournisseur avec /login / auth.json.

Appliquer les remplacements de compatibilité spécifiques à Pi uniquement lorsque cela est nécessaire

Certains services OpenAI-compatible rejettent le rôle developer ou reasoning_effort. Ajoutez ces indicateurs uniquement après que l'erreur 400 correspondante se soit produite :

"compat": {
  "supportsDeveloperRole": false,
  "supportsReasoningEffort": false
}

Ne désactivez pas les fonctionnalités de manière préventive. Une fois les demandes de base réussies, configurez thinkingLevelMap, l'entrée d'image, les paramètres d'échantillonnage ou la tarification uniquement pour le modèle exact.

Dépanner en fonction du comportement de charge de pi

• Fournisseur totalement absent de /model : vérifiez le chemin du fichier, la syntaxe JSON, baseUrl et api.
• Le fournisseur existe mais le modèle ne peut pas être sélectionné : $TOKENHUB_API_KEY n'a pas été résolu ou le fournisseur ne dispose pas d'informations d'identification enregistrées.
• 401 : confirmez que le processus pi a hérité de la variable et définissez authHeader: true si nécessaire.
• 400 ou troncature précoce : corrigez contextWindow, maxTokens ou compat ; ne vous contentez pas d’augmenter les chiffres.
• La modification n'apparaît pas : rouvrez /model au lieu de vous fier à l'ancienne sélection affichée dans la session en cours.

Références officielles

• pi : modèles personnalisés
• pi : Extension de fournisseurs personnalisés API