Documentation
Utiliser votre propre modèle d'IA
En plus des modèles du catalogue, une organisation peut faire tourner ses agents sur un modèle qu'elle sert elle-même : un modèle open source hébergé sur vos serveurs, un modèle Hugging Face, ou un modèle que vous avez entraîné. Squadico ne l'héberge pas : il l'appelle, comme n'importe quel fournisseur, à travers une API compatible OpenAI.
Ce qu'il vous faut
- Une API compatible OpenAI : les routes /v1/chat/completions (avec streaming) et, idéalement, /v1/models pour lister vos modèles.
- Une adresse en https:// joignable depuis Internet. Squadico appelle votre modèle depuis ses serveurs : une adresse du réseau interne de votre organisation (localhost, 10.x, 192.168.x…) est refusée. L'ouvrir à Squadico est à votre charge (domaine public, passerelle, reverse proxy).
- Un token d'accès, envoyé dans l'en-tête Authorization: Bearer. Il est chiffré chez Squadico et ne réapparaît jamais dans l'interface.
- Pour que l'agent utilise des outils : un modèle entraîné pour l'appel d'outils, et un serveur configuré pour l'exposer (avec vLLM : --enable-auto-tool-choice et --tool-call-parser).
- Une offre qui inclut des modèles personnalisés (voir plus bas).
Ajouter un modèle dans Squadico
- Ouvrez Paramètres de l'organisation, onglet Modèles, puis cliquez sur Ajouter une connexion.
- Choisissez le type d'API : Hugging Face (l'adresse du routeur est remplie pour vous) ou Compatible OpenAI pour tout autre serveur.
- Donnez un nom à la connexion, saisissez l'adresse de base de l'API (sans /chat/completions) et le token, puis cliquez sur Déclarer.
- Cliquez sur Lister les modèles : Squadico interroge la route /models de votre API. Cochez les modèles à ajouter. Si votre API ne liste rien, saisissez l'identifiant du modèle à la main.
- Pour chaque modèle, indiquez s'il sait utiliser des outils et lire des images (voir Capacités), puis cliquez sur Déclarer.
- Le modèle apparaît dans l'arbre des modèles, sous la connexion, avec le badge Personnalisé. Choisissez-le dans les réglages d'un agent comme n'importe quel autre modèle.
Capacités d'un modèle
- Outils : cochez seulement si le modèle et votre serveur gèrent l'appel d'outils. Un modèle sans cette capacité ne reçoit jamais les outils de l'agent ; un modèle déclaré à tort fait échouer les conversations dès que l'agent a un outil.
- Images : cochez si le modèle accepte des images en entrée (modèle de vision). Sans elle, les pièces jointes image ne lui sont pas envoyées.
- Les deux cases sont décochées par défaut : rien dans l'API ne permet à Squadico de le deviner. Vous pouvez les changer plus tard.
Modèles Hugging Face
- Le routeur Inference Providers (https://router.huggingface.co/v1) est compatible OpenAI et se paie à l'usage sur votre compte Hugging Face. Créez un token dans huggingface.co → Settings → Access Tokens, avec la permission « Make calls to Inference Providers ».
- Le routeur ne sert pas tous les modèles du Hub : seulement ceux qu'un fournisseur partenaire héberge (quelques centaines). Utilisez Lister les modèles plutôt qu'une saisie manuelle : la liste vient du routeur, et tout ce qui y figure répond.
- Les fournisseurs doivent être activés dans votre compte (huggingface.co → Settings → Inference Providers), sinon le routeur refuse même un modèle qu'il liste.
- Pour un modèle qui n'est pas dans cette liste — un modèle du Hub, privé ou fine-tuné — déployez-le sur un Inference Endpoint dédié (bouton Deploy de la page du modèle, moteur vLLM ou TGI). Déclarez ensuite une connexion Compatible OpenAI avec l'adresse de l'endpoint suivie de /v1.
Votre propre modèle
Servez votre modèle derrière un serveur compatible OpenAI, puis exposez-le en HTTPS avec un token. Exemple avec vLLM :
# Serve the model (OpenAI-compatible API on port 8000) vllm serve your-org/your-model \ --api-key "$SQUADICO_TOKEN" \ --enable-auto-tool-choice \ --tool-call-parser hermes # Then expose it over HTTPS on a public address (reverse proxy, gateway…) # and declare https://models.your-company.com/v1 in Squadico.
- Autres serveurs compatibles : TGI, SGLang, Ollama, LM Studio, ou un service géré (SageMaker, Vertex AI, Azure ML) en mode compatible OpenAI.
- Si votre API n'est pas compatible OpenAI, placez LiteLLM devant : il traduit vers ce format.
- Le modèle doit avoir un template de chat correct, sinon ses réponses seront incohérentes.
Vérifier votre API avant de la déclarer
Ces deux appels sont ceux que fait Squadico. S'ils répondent depuis une machine hors de votre réseau, la connexion fonctionnera.
BASE_URL=https://models.your-company.com/v1
# GET /v1/models: the models Squadico offers to add
curl -s "$BASE_URL/models" -H "Authorization: Bearer $TOKEN"
# POST /v1/chat/completions: a conversation, as an agent sends it
curl -s "$BASE_URL/chat/completions" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"model": "your-org/your-model", "messages": [{"role": "user", "content": "Hello"}]}'Modèles personnalisés par offre
Le nombre de modèles personnalisés (toutes connexions confondues) dépend de l'offre de l'organisation. Leur consommation n'est pas facturée par Squadico : elle l'est par votre serveur ou votre fournisseur.
| Offre | Modèles personnalisés |
|---|---|
| Gratuit | Non inclus |
| Pro | 1 |
| Business | 10 |
| Entreprise | Illimité |
Dépannage
| Symptôme | Cause et solution |
|---|---|
| « Saisissez une adresse joignable depuis Internet » | L'adresse est en http://, ou elle pointe vers une adresse privée. Exposez l'API en https:// sur une adresse publique. |
| « The requested model … is not supported by any provider you have enabled » | Hugging Face : aucun fournisseur d'inférence ne sert ce modèle, ou les fournisseurs sont désactivés dans votre compte. Prenez un modèle proposé par Lister les modèles, activez les fournisseurs, ou déployez le modèle sur un Inference Endpoint. |
| « Le fournisseur IA ne propose pas le modèle de cet agent » | L'identifiant du modèle ne correspond à aucun modèle chargé par votre serveur. Vérifiez-le avec GET /v1/models : c'est l'identifiant exact qu'il faut déclarer. |
| « Le fournisseur IA a refusé la clé » | Le token est invalide ou expiré. Mettez-le à jour depuis la connexion. |
| L'agent échoue dès qu'il a un outil | Le modèle est déclaré avec Outils alors que votre serveur n'expose pas l'appel d'outils. Décochez Outils, ou activez-le sur le serveur (vLLM : --enable-auto-tool-choice --tool-call-parser …). |
| « Non listé par l'API » sur un modèle saisi à la main | Votre API ne liste pas ce modèle : vérifiez l'identifiant. Si votre serveur ne liste qu'une partie de ses modèles, vous pouvez l'ajouter quand même. |
| Impossible d'ajouter une connexion | Votre offre n'inclut pas de modèle personnalisé, ou son quota est atteint. Retirez un modèle ou passez à une offre supérieure. |