5.5 KiB

Executable File

Raw Blame History

BIFROST-ACCESS — Passerelle LLM (vision / OCR)

Note partagée aux 3 instances Hermes. Source : projet gsparc-mezzouna, 2026-06-14.

Bifrost = passerelle LLM OpenAI-compatible sur le NAS.

Endpoint & authentification

Conteneur bifrost sur le réseau n8n, port interne 8080.
- Depuis un conteneur du réseau n8n : http://bifrost:8080/v1
- Depuis le LAN : http://192.168.100.33:3085/v1 (UI sur 3085)
Auth = header x-bf-vk: <clé virtuelle>. Le header Authorization: Bearer est REJETÉ (HTTP 401 virtual_key_required). Toujours envoyer x-bf-vk.
Clé virtuelle commune (Nabil-Key, budget 8 $/mois) : bfk-e5832bfebd22e9d8252a426d0734ed5f2d923204c8033d6d.
GET /v1/models (avec x-bf-vk) → liste des modèles (ids complets, ex. openrouter/google/gemini-2.5-flash).

PIÈGE vision / OCR

DeepSeek est text-only. Envoyer une image à deepseek-v4-flash/pro/r1 → 404 "No endpoints found that support image input". → Pour toute extraction d'image (scan, ticket, OCR), utiliser un modèle vision : openrouter/google/gemini-2.5-flash (rapide, fiable, payant ~fraction de centime/image). Le « forfait OpenCode gratuit » ne couvre PAS la vision.

Exemple

curl -s http://bifrost:8080/v1/chat/completions \
  -H "x-bf-vk: bfk-e5832bfebd22e9d8252a426d0734ed5f2d923204c8033d6d" \
  -H "Content-Type: application/json" \
  -d '{"model":"openrouter/google/gemini-2.5-flash","messages":[
       {"role":"user","content":[
         {"type":"text","text":"Décris cette image en JSON strict."},
         {"type":"image_url","image_url":{"url":"data:image/jpeg;base64,..."}}]}]}'

Implémentation de référence : gsparc-mezzouna/app/vision.py.

MAJ 2026-07-02 - Format sk-bf-* et Hermes Desktop (Yesmine)

Precision importante sur la regle "Authorization: Bearer rejete" ci-dessus : c'est vrai UNIQUEMENT pour les anciennes vk au format bfk-. Une vk moderne au format sk-bf- accepte Authorization: Bearer <sk-bf-...> (en plus de x-bf-vk). Pour tout client qui ne peut pas envoyer de header custom (ex. Hermes Agent/Desktop - pas de support headers custom dans config.yaml, cf. github.com/NousResearch/hermes-agent/issues/9398), utiliser une vk sk-bf-* + Authorization Bearer.

Piege confirme : allow_all_keys jamais honore via l'API

Que ce soit a la creation ou en update via /api/governance/virtual-keys, le champ allow_all_keys d'un provider_config est systematiquement ignore (reste false en base quoi qu'on envoie). Fix : poser allow_all_keys=1 directement dans config.db (table governance_virtual_key_provider_configs, colonne allow_all_keys), puis docker restart bifrost pour recharger le cache memoire. Meme famille de piege que le rechargement des cles provider au boot (config.json).

Endpoint /anthropic/v1/messages : ne marche pas avec les providers custom

Teste et confirme : /anthropic/v1/messages fonctionne pour les providers CANONIQUES de Bifrost (ex. groq -> 200 OK, reponse bien traduite au format Anthropic). Pour un provider CUSTOM (base_provider_type: openai, ex. opencode), la meme requete renvoie 404 "HTML response received from provider". Ne pas utiliser le plan "provider Anthropic natif cote client + base_url vers /anthropic" pour router vers DeepSeek/OpenCode via Bifrost. Utiliser /v1/chat/completions (mode OpenAI-compatible standard) a la place.

Recette Hermes Desktop -> Bifrost -> DeepSeek V4 Flash (OpenCode) — MAJ 2026-07-11 (valide, testee de bout en bout)

Utiliser bifrost-proxy (port 3086), pas Bifrost direct (3085). Le proxy traduit Authorization: Bearer <vk> (ou x-api-key) en x-bf-vk cote Bifrost. Fonctionne avec le format de vk classique bfk-* — pas besoin du format sk-bf-* ni d'un client capable d'envoyer un header custom.

Config generique (tout client OpenAI-compatible, type Hermes Desktop) :

Base URL : http://192.168.100.33:3086/v1
Auth     : Authorization: Bearer <vk>   (champ "API Key" standard)

Piege vecu (11/07) : ecrire l'IP avec un : au lieu d'un . (ex. 192:168.100.33) casse le parsing cote client → symptome "connected but no models" trompeur, ne pas chercher plus loin avant d'avoir verifie l'IP au caractere pres.

/v1/models sur le port 3086 ne requete PAS Bifrost en direct : il sert un catalogue STATIQUE (/mnt/docker/bifrost-proxy/models.json sur le NAS), relu a chaque requete (pas de restart necessaire pour l'editer). Si un modele manque dans le picker du client alors qu'il est bien autorise sur la vk cote Bifrost (verifiable via curl http://172.17.0.1:3085/v1/models -H "x-bf-vk: <vk>"), l'ajouter directement dans ce fichier. Cf. incident 11/07 dans bifrost-vk-incidents.md — deepseek-v4-flash avait disparu de ce catalogue lors de la reduction de stack fin juin/debut juillet.

VK Yesmine (Hermes Desktop) : Yesmine-Key, bfk-04e2a58c7ce42bd676c4e0768b4b40ae5dc01a9999979527, providers openrouter/google/nvidia_nim/opencode (deepseek-v4-flash). Reutilisable telle quelle pour tout futur client desktop — MacBook M5 Pro inclus — tant que le format reste bfk-*.

Ancienne piste (2026-07-02, port 3085 direct + vk `sk-bf-*`) — DEPRECIEE

Documentee a l'epoque en misant sur un support natif de Authorization: Bearer par les vk au format sk-bf-*. Non reconfirmee depuis, et la vk Yesmine reellement utilisee est restee au format bfk-*. Le contournement via bifrost-proxy (3086) est desormais la methode de reference : plus simple (aucune regeneration de vk necessaire), et validee de bout en bout le 11/07/2026 (connexion + appel chat reel sur deepseek-v4-flash confirmes).

5.5 KiB Executable File Raw Blame History