Router l'IDE d'un développeur vers la passerelle

Désigner la passerelle dans la configuration d'un poste : elle est le seul chemin du poste vers le modèle.

Le poste ne joint pas le moteur d’inférence : il ne connaît que l’adresse de la passerelle, qui authentifie, applique la politique, journalise, et joint seule le moteur (livre blanc sécurité V3, sections 3.3 et 8.2). Cette page décrit la configuration du poste qui désigne la passerelle.

Le rôle de ce détour est décrit dans Le rôle de la passerelle.

Ce que le poste doit dire

Un modèle de la configuration Lemniscate désigne la passerelle par son apiBase et s’authentifie auprès d’elle avec la clé du compte du développeur.

Dans ~/.lemniscate/workstation.yaml :

models:
  - name: Code principal (passerelle)
    provider: openai
    model: any
    apiBase: https://passerelle.interne:6001/code-principal/v1
    apiKey: sk-lemniscate-<la-clé-du-développeur>
    roles:
      - chat

Champ par champ :

apiBase porte l’adresse de la passerelle et le nom de l’endpoint : https://<hôte>:<port>/<nom-de-l-endpoint>/v1. Le premier segment du chemin désigne l’endpoint ; ce qui suit est relayé tel quel au moteur d’inférence. L’adresse est en https:// : les flux entre composants sont chiffrés en TLS (livre blanc sécurité V3, section 6.2).
provider désigne le dialecte que l’IDE parle, c’est-à-dire la forme des requêtes et des réponses. La passerelle joint le moteur par une API compatible OpenAI : la valeur est openai. L’endpoint, côté passerelle, décide du moteur appelé.
model est ignoré. La passerelle réécrit le modèle du corps de la requête avec celui que l’endpoint désigne. Toute valeur convient ; une valeur qui ressemble à un vrai nom de modèle induit en erreur le lecteur suivant du fichier.
apiKey est la clé du compte sur la passerelle. Elle ne vaut que contre la passerelle, qui retire l’en-tête d’authentification de l’appelant avant de relayer. Si le moteur exige une clé, la passerelle la lit dans une variable d’environnement de son propre conteneur ; cette clé n’est pas transmise au poste.
roles vaut chat, summarize, apply et edit quand il est absent. Nommez-les pour restreindre ce modèle à un usage.

Le port 6001 est le port d’écoute par défaut de la passerelle ; sa variable PORT le redéfinit.

Pour n’appliquer ce routage qu’à un projet, le même bloc models se pose dans un fichier de .lemniscate/models/ à la racine du dépôt concerné.

La liste complète des clés acceptées par ce fichier est en référence.

Vérifier le nom de l’endpoint

C’est la faute la plus fréquente, et la passerelle la nomme : un endpoint inconnu reçoit un 404 dont le corps liste les endpoints qui existent.

{
  "error": "Unknown endpoint: code-principale",
  "available": ["code-principal", "completion-rapide"]
}

Les autres refus à reconnaître :

Réponse	Ce qu’elle veut dire
`401`	clé absente ou inconnue de la passerelle
`403`	l’endpoint est désactivé, ou aucun rôle du compte ne porte le droit de l’appeler
`500` nommant une variable	le moteur attend une clé dont la variable manque à l’environnement de la passerelle

Le profil de construction serverless ajoute deux refus, liés aux plans de dépense : 403 pour un compte sans plan, 402 pour un compte qui a atteint le plafond mensuel de son plan. Ils se lèvent par des gestes différents : Plafonner la dépense d’un client. Un service qui ne répond pas du tout relève de La passerelle refuse de démarrer.

La passerelle accepte la clé sous Authorization: Bearer <clé> comme sous x-api-key: <clé>.

Derrière un pare-feu d’entreprise

Les deux moitiés du chemin se règlent séparément.

Du poste à la passerelle, l’IDE traverse un proxy d’entreprise : la configuration accepte requestOptions avec proxy, noProxy, caBundlePath et clientCertificate, à la racine comme par modèle.

De la passerelle au moteur d’inférence, à l’intérieur de votre périmètre, l’appel se règle par variables d’environnement sur le service de la passerelle :

Variable	Ce qu’elle règle
`HTTPS_PROXY`, `HTTP_PROXY`	le proxy interne à traverser pour joindre le moteur
`NO_PROXY`	les destinations à joindre en direct, avec jokers, suffixes et ports
`NODE_EXTRA_CA_CERTS`	une autorité de certification interne, ajoutée au magasin de Node
`UPSTREAM_TLS_CA_FILE`	une autorité propre au trajet sortant de la passerelle
`UPSTREAM_TLS_CLIENT_CERT_FILE`, `UPSTREAM_TLS_CLIENT_KEY_FILE`	le certificat client, quand le moteur exige du mTLS

Les noms en minuscules (https_proxy, http_proxy) sont acceptés, avec la même précédence que dans le reste du produit.

Un réglage invalide arrête le démarrage : une variable de proxy qui n’est pas une adresse, ou un NODE_EXTRA_CA_CERTS illisible, sont refusés au lancement avec le nom de la variable en cause.

Si vous configurez du mTLS, le certificat client n’écrase pas la confiance d’entreprise : le magasin de confiance est assemblé, et NODE_EXTRA_CA_CERTS continue de s’appliquer.

Si la réponse arrive d’un bloc au lieu de s’écrire

Un proxy qui met les réponses en tampon casse l’affichage mot à mot, quoi que fasse la passerelle. Le développeur voit un assistant muet pendant plusieurs secondes, puis une réponse qui apparaît d’un coup. Le temps total est normal ; sa répartition change.

C’est le comportement par défaut de beaucoup d’équipements qui inspectent le contenu : inspecter suppose d’avoir la réponse entière avant de la relayer.

Pour le vérifier chez vous, comparez le même appel avec et sans le proxy :

Depuis un poste qui traverse le proxy, lancez une demande dont la réponse est longue.
Refaites la même demande depuis un poste ou un réseau qui ne le traverse pas.

Si les mots s’écrivent au fil de l’eau dans le second cas et pas dans le premier, le tampon est dans le proxy. Rien n’est à corriger côté produit.

Sur l’autre moitié du chemin, entre la passerelle et le moteur, la passerelle mesure le rythme d’arrivée des réponses longues. Quand plusieurs réponses arrivent en une seule rafale, elle l’écrit sur sa sortie d’erreur sous le préfixe [upstream-buffering], une fois, puis tous les cent cas. Son silence ne prouve rien : elle ne voit pas le trajet entre le poste et elle.

Le réglage dépend de l’équipement. À titre d’exemple, mitmproxy tamponne par défaut et relaie au fil de l’eau avec --set stream_large_bodies=1. Cherchez l’équivalent dans le vôtre : la notion s’appelle streaming, pass-through ou no buffering.

Pour le support, c’est la première question à poser quand un client signale un assistant lent à répondre alors que les mesures côté serveur sont bonnes.

Ce que ce trajet expose

À peser au moment de choisir sur quel réseau poser la passerelle.

Le trajet du poste à la passerelle porte les demandes et la clé du développeur. Il est chiffré en TLS (livre blanc sécurité V3, section 6.2) : la passerelle termine TLS quand vous lui donnez TLS_CERT_FILE et TLS_KEY_FILE, et l’apiBase du poste est alors en https://. Sans ces deux variables, la passerelle écoute en clair et l’annonce au démarrage ; un terminateur TLS placé devant elle doit alors chiffrer le flux des postes.

L’adresse du moteur est une donnée de la base, lue dans la colonne base_url du moteur déclaré. La console vérifie la forme de cette adresse (une URL absolue, en https://, ou en http:// avec une acceptation explicite), pas sa destination. Qui peut écrire dans la base peut diriger les demandes vers une autre adresse. Ce qui protège cette colonne est la console : elle exige un rôle par route, sait déléguer l’authentification à l’annuaire de votre organisation, et journalise les actes d’administration (attribution d’un rôle, retrait, révocation d’un sujet). Un couple d’identifiants d’amorçage partagé reste toléré pour le premier démarrage ; retirez-le une fois les rôles en place.

Ce que cette page ne décrit pas

La configuration accepte un fournisseur nommé lemniscate-proxy, traité à part dans le schéma, avec ses propres champs orgScopeId et onPremProxyUrl. Ce n’est pas le chemin décrit ici, ni la façon de joindre votre passerelle.

Son implémentation pointe par défaut sur un service hébergé par l’éditeur, dont rien dans le dépôt n’atteste l’existence ni l’exploitation ; l’inventaire des surfaces le classe pour cette raison en état indéterminé. Le mode onPremProxyUrl est autonome, et aucun élément du dépôt ne permet d’en écrire la procédure sans l’inventer.

Sur les autres surfaces héritées qui parlent à ce même service non opéré : Ce qui n’existe pas.