Comment utiliser une passerelle LLM avec Corriger avec l'IA¶

Par défaut, le Boost advisor qui exécute Corriger avec l'IA appelle directement votre fournisseur LLM avec la clé API du fournisseur. Pour acheminer ces appels via votre propre passerelle LLM compatible OpenAI, définissez quelques variables supplémentaires dans le pipeline qui exécute l'advisor. Rien ne change dans le tableau de bord Boost Security. Lorsqu'aucune de ces variables n'est définie, l'advisor continue d'appeler directement le fournisseur.

Avant de commencer¶

Le Boost advisor est configuré pour votre SCM, comme décrit dans les prérequis de Corriger avec l'IA.
Votre passerelle expose l'API de complétion de chat OpenAI, avec appel d'outils. L'advisor envoie des outils à chaque appel et ne peut pas fonctionner sans eux.
Votre passerelle est accessible via HTTPS depuis les runners CI du pipeline de l'advisor. L'advisor appelle la passerelle depuis votre propre pipeline, jamais depuis les serveurs Boost Security.
Vous savez quelles méthodes d'authentification votre passerelle requiert : identifiants client OAuth2, une clé API envoyée dans un en-tête, ou les deux.

Variables de passerelle¶

Ajoutez ces variables aux secrets ou variables du pipeline de l'advisor. Vous disposez déjà de BOOST_LLM_MODEL et BOOST_LLM_KEY depuis la configuration de l'advisor. Stockez au moins l'ID client, le secret client et BOOST_LLM_KEY en tant que secrets. Sur GitHub, stockez-les tous en tant que secrets.

Variable	Doit être secrète	Requise pour	Peut être laissée vide	Valeur
`BOOST_LLM_MODEL`	Non	Toujours	Non	Le nom du modèle tel que votre passerelle le connaît.
`BOOST_LLM_API_FORMAT`	Non	Toute passerelle	Oui	`openai`, la seule valeur prise en charge. La définir fait appeler votre passerelle par l'advisor.
`BOOST_LLM_BASE_URL`	Non	Toute passerelle	Oui	L'URL de base de votre passerelle, commençant par `https://`. L'advisor envoie ses requêtes à `<URL de base>/chat/completions` et n'ajoute pas `/v1`, incluez-le donc dans l'URL de base si votre passerelle en a besoin.
`BOOST_LLM_OAUTH_TOKEN_URL`	Non	OAuth2	Oui	Le point de terminaison de jeton de votre fournisseur d'identité, commençant par `https://`. Le définir active OAuth2.
`BOOST_LLM_OAUTH_CLIENT_ID`	Oui	OAuth2	Oui	L'ID client.
`BOOST_LLM_OAUTH_CLIENT_SECRET`	Oui	OAuth2	Oui	Le secret client.
`BOOST_LLM_OAUTH_SCOPE`	Non	OAuth2, optionnel	Oui	Le scope envoyé dans la requête de jeton, lorsque votre fournisseur d'identité en a besoin.
`BOOST_LLM_API_KEY_HEADER`	Non	Clé API	Oui	Le nom de l'en-tête qui porte la clé API, par exemple `HUB_API_KEY`, ou `Authorization`. Le définir active la méthode de clé API.
`BOOST_LLM_KEY`	Oui	Direct, ou clé API	Oui	Sans passerelle : la clé API de votre fournisseur LLM. Avec une passerelle : la valeur envoyée dans l'en-tête de clé API, telle quelle. Par exemple, pour l'en-tête `Authorization`, une valeur telle que `Bearer sk-…`. Non nécessaire pour OAuth2 seul.

L'advisor traite une variable marquée Peut être laissée vide comme non définie lorsqu'elle est absente, lorsque sa valeur est vide, ou lorsque sa valeur est le texte $(<nom de la variable>), tel qu'Azure DevOps transmet une variable qui n'est pas définie. Vous pouvez donc transmettre toutes ces variables à l'advisor et laisser vides celles des méthodes que vous n'utilisez pas. BOOST_LLM_MODEL doit toujours avoir une valeur : l'exécution échoue lorsqu'elle est absente.

Méthodes d'authentification¶

Votre passerelle peut requérir une méthode ou les deux. Lorsque les deux sont définies, l'advisor envoie les deux à chaque appel.

Identifiants client OAuth2

Définissez BOOST_LLM_OAUTH_TOKEN_URL, BOOST_LLM_OAUTH_CLIENT_ID, BOOST_LLM_OAUTH_CLIENT_SECRET, et optionnellement BOOST_LLM_OAUTH_SCOPE.

Au début de chaque exécution, l'advisor obtient un jeton d'accès depuis le point de terminaison de jeton et l'envoie sous la forme Authorization: Bearer <jeton>. Votre fournisseur d'identité doit :

Prendre en charge le grant client credentials, avec le client authentifié via HTTP Basic (client_secret_basic).
Retourner le jeton dans le champ access_token de la réponse.
Émettre un jeton qui dure pendant toute l'exécution. L'advisor obtient un jeton par exécution et ne le rafraîchit pas. Une exécution produit un correctif et se termine largement dans la durée de vie typique d'une heure du jeton.
Émettre le bon jeton sans paramètre audience, que l'advisor n'envoie pas. Pour les fournisseurs d'identité qui en ont besoin, comme Auth0, définissez l'API de votre passerelle comme audience par défaut du locataire.

En-tête de clé API

Définissez BOOST_LLM_API_KEY_HEADER avec le nom de l'en-tête, et BOOST_LLM_KEY avec sa valeur. L'advisor envoie la valeur telle quelle, à chaque appel.

Les deux

Définissez les variables des deux méthodes. L'en-tête de clé API ne peut pas être Authorization, puisqu'OAuth2 l'utilise déjà.

Transmettre les variables à l'advisor¶

GitHub

Ajoutez les variables en tant que secrets du dépôt .boost. L'étape Run boost-advisor du workflow de l'advisor les mappe toutes dans son env. Un secret non défini parvient à l'advisor comme une valeur vide, ce qui est considéré comme non défini, de sorte que le même workflow fonctionne pour chaque méthode d'authentification. Créez uniquement les secrets des méthodes que vous utilisez, plus BOOST_LLM_MODEL. Si votre workflow a été créé auparavant, remplacez son étape Run boost-advisor par :

      - name: Run boost-advisor
        env:
          BOOST_API_KEY: ${{ secrets.BOOST_API_TOKEN }}
          BOOST_SCM_TOKEN: ${{ secrets.BOOST_SCM_TOKEN }}
          BOOST_LLM_MODEL: ${{ secrets.BOOST_LLM_MODEL }}
          BOOST_LLM_KEY: ${{ secrets.BOOST_LLM_KEY }}
          BOOST_LLM_API_FORMAT: ${{ secrets.BOOST_LLM_API_FORMAT }}
          BOOST_LLM_BASE_URL: ${{ secrets.BOOST_LLM_BASE_URL }}
          BOOST_LLM_OAUTH_TOKEN_URL: ${{ secrets.BOOST_LLM_OAUTH_TOKEN_URL }}
          BOOST_LLM_OAUTH_CLIENT_ID: ${{ secrets.BOOST_LLM_OAUTH_CLIENT_ID }}
          BOOST_LLM_OAUTH_CLIENT_SECRET: ${{ secrets.BOOST_LLM_OAUTH_CLIENT_SECRET }}
          BOOST_LLM_OAUTH_SCOPE: ${{ secrets.BOOST_LLM_OAUTH_SCOPE }}
          BOOST_LLM_API_KEY_HEADER: ${{ secrets.BOOST_LLM_API_KEY_HEADER }}
          PAYLOAD: ${{ inputs.payload }}
        run: |
          echo "$PAYLOAD" | /tmp/boost-advisor/latest -

GitLab

Ajoutez les variables dans Settings → CI/CD → Variables du projet boost, avec Masked sélectionné pour les secrets. Le job de l'advisor les lit telles quelles, sans changement à .gitlab-ci.yml. N'ajoutez que les variables des méthodes que vous utilisez. Une variable absente, ou ajoutée avec une valeur vide, est considérée comme non définie.

Bitbucket

Ajoutez les variables dans Repository settings → Pipelines → Repository variables du dépôt .boost, avec Secured sélectionné pour les secrets. L'étape de l'advisor les lit telles quelles, sans changement à bitbucket-pipelines.yml. N'ajoutez que les variables des méthodes que vous utilisez. Une variable absente, ou ajoutée avec une valeur vide, est considérée comme non définie.

Azure DevOps

Ajoutez les variables au groupe de variables boostsecurityio, avec l'icône de cadenas sélectionnée pour les secrets. L'étape Run boost-advisor du pipeline de l'advisor les mappe toutes dans son env. Une variable absente du groupe parvient à l'advisor sous forme du texte $(<nom de la variable>), et une variable avec une valeur vide comme valeur vide. Les deux sont considérées comme non définies, de sorte que le même pipeline fonctionne pour chaque méthode d'authentification. N'ajoutez au groupe que les variables des méthodes que vous utilisez, plus BOOST_LLM_MODEL. Si votre pipeline a été créé auparavant, remplacez son étape Run boost-advisor par :

    - script: |
        echo "$PAYLOAD" | /tmp/boost-advisor/latest -
      displayName: Run boost-advisor
      env:
        BOOST_SCM_TOKEN: $(BOOST_SCM_TOKEN)
        BOOST_API_KEY: $(BOOST_API_TOKEN)
        BOOST_LLM_MODEL: $(BOOST_LLM_MODEL)
        BOOST_LLM_KEY: $(BOOST_LLM_KEY)
        BOOST_LLM_API_FORMAT: $(BOOST_LLM_API_FORMAT)
        BOOST_LLM_BASE_URL: $(BOOST_LLM_BASE_URL)
        BOOST_LLM_OAUTH_TOKEN_URL: $(BOOST_LLM_OAUTH_TOKEN_URL)
        BOOST_LLM_OAUTH_CLIENT_ID: $(BOOST_LLM_OAUTH_CLIENT_ID)
        BOOST_LLM_OAUTH_CLIENT_SECRET: $(BOOST_LLM_OAUTH_CLIENT_SECRET)
        BOOST_LLM_OAUTH_SCOPE: $(BOOST_LLM_OAUTH_SCOPE)
        BOOST_LLM_API_KEY_HEADER: $(BOOST_LLM_API_KEY_HEADER)
        PAYLOAD: ${{ parameters.payload }}

Warning

Mappez les variables dans env, pas avec des lignes export BOOST_LLM_BASE_URL=$(BOOST_LLM_BASE_URL) dans le script. Dans un script, une variable absente du groupe reste sous forme du texte $(BOOST_LLM_BASE_URL), que bash exécute comme une commande.

Harness

L'exemple de pipeline de l'advisor déclare déjà les variables de passerelle dans les envVariables de son étape Run Boost Advisor. Chacune lit une variable de projet et transmet une valeur vide lorsque cette variable n'est pas définie, ce que l'advisor traite comme non défini. Vous ne créez donc que ce dont vos méthodes ont besoin :

Toute passerelle : créez la variable de projet BOOST_LLM_API_FORMAT, définie sur openai, et la variable de projet BOOST_LLM_BASE_URL.
Identifiants client OAuth2 : créez la variable de projet BOOST_LLM_OAUTH_TOKEN_URL, et optionnellement BOOST_LLM_OAUTH_SCOPE. Créez les secrets BOOST_LLM_OAUTH_CLIENT_ID et BOOST_LLM_OAUTH_CLIENT_SECRET. Pour OAuth2 seul, le secret BOOST_LLM_KEY n'est pas nécessaire.
En-tête de clé API : créez la variable de projet BOOST_LLM_API_KEY_HEADER, et définissez le secret BOOST_LLM_KEY avec la valeur de l'en-tête.

Harness ne fait pas échouer l'exécution sur un secret qui n'existe pas, mais la valeur qu'il transmet est imprévisible. Ainsi, la command de l'étape supprime l'ID client et le secret OAuth2 lorsque BOOST_LLM_OAUTH_TOKEN_URL est vide.

Si votre pipeline a été créé auparavant, ajoutez ces lignes aux envVariables de l'étape :

# Variables de passerelle LLM optionnelles : une variable de projet non définie est transmise comme vide, et l'advisor l'ignore
BOOST_LLM_API_FORMAT: <+<+variable.BOOST_LLM_API_FORMAT> == null?"":variable.BOOST_LLM_API_FORMAT>
BOOST_LLM_BASE_URL: <+<+variable.BOOST_LLM_BASE_URL> == null?"":variable.BOOST_LLM_BASE_URL>
BOOST_LLM_OAUTH_TOKEN_URL: <+<+variable.BOOST_LLM_OAUTH_TOKEN_URL> == null?"":variable.BOOST_LLM_OAUTH_TOKEN_URL>
BOOST_LLM_OAUTH_SCOPE: <+<+variable.BOOST_LLM_OAUTH_SCOPE> == null?"":variable.BOOST_LLM_OAUTH_SCOPE>
BOOST_LLM_API_KEY_HEADER: <+<+variable.BOOST_LLM_API_KEY_HEADER> == null?"":variable.BOOST_LLM_API_KEY_HEADER>
# Identifiants client OAuth2 : la commande les supprime lorsque BOOST_LLM_OAUTH_TOKEN_URL est vide
BOOST_LLM_OAUTH_CLIENT_ID: <+secrets.getValue('BOOST_LLM_OAUTH_CLIENT_ID')>
BOOST_LLM_OAUTH_CLIENT_SECRET: <+secrets.getValue('BOOST_LLM_OAUTH_CLIENT_SECRET')>

Puis ajoutez ces lignes à sa command, juste après set -e :

# OAuth2 nécessite l'URL de jeton et les deux secrets client ensemble : sans l'URL, les supprimer
if [ -z "$BOOST_LLM_OAUTH_TOKEN_URL" ]; then unset BOOST_LLM_OAUTH_CLIENT_ID BOOST_LLM_OAUTH_CLIENT_SECRET BOOST_LLM_OAUTH_SCOPE; fi

La même forme rend n'importe quelle variable de projet optionnelle : <+<+variable.NAME> == null?"":variable.NAME>.

Erreurs de configuration¶

Lorsque les variables ne s'accordent pas entre elles, l'exécution de l'advisor échoue dans votre pipeline avec l'un de ces messages :

Message	Cause
`token is required`	Aucune passerelle n'est définie, et `BOOST_LLM_KEY` n'est pas défini non plus.
`oauth_* and api_key_header require api_format`	Les variables OAuth2 ou de clé API sont définies, mais pas `BOOST_LLM_API_FORMAT`.
`api_format requires an https base_url`	`BOOST_LLM_BASE_URL` n'est pas défini, ou ne commence pas par `https://`.
`oauth_token_url must be https`	`BOOST_LLM_OAUTH_TOKEN_URL` ne commence pas par `https://`.
`oauth_token_url requires oauth_client_id and oauth_client_secret`	L'URL de jeton est définie sans l'ID client et le secret client.
`oauth_* requires oauth_token_url`	L'ID client, le secret client ou le scope est défini sans l'URL de jeton.
`api_key_header must be a valid HTTP header name`	`BOOST_LLM_API_KEY_HEADER` n'est pas un nom d'en-tête valide.
`api_key_header requires token`	`BOOST_LLM_API_KEY_HEADER` est défini sans `BOOST_LLM_KEY`.
`api_format requires oauth_token_url or api_key_header`	Une passerelle est définie, sans méthode d'authentification.
`only one auth method may set Authorization`	OAuth2 est défini, et `BOOST_LLM_API_KEY_HEADER` est `Authorization`.