> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Utiliser Weights & Biases avec des assistants IA
> Utilisez W&B Skills et le serveur MCP Weights & Biases pour automatiser vos flux de travail, interroger vos données et effectuer des recherches dans la documentation.
Weights & Biases s’intègre aux assistants IA de deux manières complémentaires :
* **W\&B Skills** apprend aux agents de développement à utiliser efficacement Weights & Biases dans votre code et vos flux de travail d’analyse.
* **Le serveur MCP Weights & Biases** connecte les assistants IA à vos données et à la documentation Weights & Biases afin qu’ils puissent répondre à des questions en langage naturel sur vos runs, vos traces, vos évaluations et vos artifacts.
Utilisez Skills si vous souhaitez que votre agent de développement écrive ou modifie du code qui exploite Weights & Biases. Utilisez le serveur MCP si vous souhaitez qu’un assistant IA interroge vos données Weights & Biases en temps réel ou effectue des recherches dans la documentation Weights & Biases. Les deux sont complémentaires : Skills fournit des modèles de flux de travail, tandis que MCP donne accès aux données.
Selon l’intégration, Weights & Biases fonctionne avec plusieurs des principaux agents de développement, IDE et assistants de chat, notamment :
* Claude Code
* Codex
* Cursor
* Gemini CLI
* Visual Studio Code (VS Code)
* Mistral LeChat
* Claude Desktop
Pour obtenir la liste complète des agents pris en charge par W\&B Skills, consultez la [documentation de la CLI W\&B Skills](https://github.com/vercel-labs/skills#supported-agents).
W\&B Skills
Les W\&B Skills sont des ensembles d’instructions réutilisables qui apprennent aux agents de développement à utiliser efficacement Weights & Biases. Plutôt que de guider vous-même votre agent dans les API et les bonnes pratiques de W\&B, installez des Skills pour que l’agent prenne en charge de manière autonome le suivi des expériences, le traçage, les évaluations et la surveillance.
Fonctionnalités
Les skills couvrent à la fois le [SDK Python W\&B](/fr/products/wandb/ref) (runs d’entraînement, métriques, artifacts, sweeps) et le [SDK Weave](/fr/products/wandb/weave/reference/python-sdk) (traces, évaluations, évaluateurs). Ils incluent des bibliothèques utilitaires, de la documentation de référence et des modèles d’analyse de données qui permettent à votre agent de prendre en charge les flux de travail suivants.
| Flux de travail | Fonctionnalités |
| - | - |
| **Entraînement de modèles** | - Journaliser des métriques et des médias enrichis pendant l’entraînement et le fine-tuning.
- Suivre et comparer des expériences.
- Analyser les runs et les résultats, comme les courbes de perte et les scores de précision.
- Ajuster les hyperparamètres.
|
| **Création d’agents** | - Tracer des applications d’IA agentiques.
- Analyser les traces et classer les modes de défaillance.
- Évaluer des modèles et des agents à l’aide de datasets étiquetés.
- Exécuter des évaluations en ligne pour la surveillance en production.
|
Prérequis
Les W\&B Skills nécessitent les éléments suivants :
* [Node.js](https://nodejs.org/) pour la commande `npx`.
* Une clé API Forge. Créez-en une sur [forge.coreweave.com/settings#apikeys](https://forge.coreweave.com/settings#apikeys), puis définissez-la comme variable d’environnement. Remplacez `[YOUR-API-KEY]` par votre clé API :
```bash theme={"system"}
export WANDB_API_KEY="[YOUR-API-KEY]"
```
* Facultatif : définissez le nom de votre projet Weights & Biases dans la variable d’environnement `WANDB_PROJECT`. Votre agent peut ainsi cibler le bon projet Weights & Biases sans que vous ayez à le préciser à chaque fois.
Installer W\&B Skills
Choisissez une installation globale pour rendre les Skills disponibles dans tous vos projets, ou une installation propre à un projet pour limiter la portée des Skills à ce seul projet.
Pour installer W\&B Skills de façon globale, pour l’ensemble de vos projets, utilisez l’option `--global` :
```bash theme={"system"}
npx skills add wandb/skills --skill '*' --yes --global
```
Pour installer les Skills uniquement pour le projet en cours, exécutez la commande d’installation depuis le répertoire de votre projet, sans l’option `--global` :
```bash theme={"system"}
npx skills add wandb/skills --skill '*' --yes
```
Installez les Skills pour des agents précis à l’aide de l’option `--agent` :
```bash theme={"system"}
npx skills add wandb/skills \
--agent claude-code \
--skill '*' \
--yes \
--global
```
Pour obtenir la liste des options `--agent` et `--skill`, consultez la [documentation de la CLI skills de Vercel Labs](https://github.com/vercel-labs/skills#supported-agents).
Une fois l’installation terminée, votre agent a accès aux W\&B Skills et peut prendre en charge les tâches liées à Weights & Biases.
Utiliser W\&B Skills
Demandez à votre agent d’effectuer des tâches liées à Weights & Biases pour votre projet. Les exemples de prompts suivants illustrent quelques-unes des tâches que votre agent peut réaliser avec W\&B Skills :
* « Journalise les métriques d’entraînement de mon modèle PyTorch dans Weights & Biases. »
* « Analyse les courbes de perte de mes 10 derniers runs et identifie la configuration la plus performante. »
* « Trace mon agent LangChain et journalise les résultats dans Weave. »
* « Lance une évaluation de mon agent sur le dataset de test et résume les résultats. »
* « Identifie les modes de défaillance de ma dernière évaluation et classe-les. »
* « Compare les configurations du run A et du run B, et montre-moi les différences. »
Conseils d’utilisation de W\&B Skills
Skills donne de meilleurs résultats avec des requêtes précises qu’avec des questions générales et ouvertes. Le tableau suivant compare des prompts recommandés à des prompts trop vagues.
| Recommandé | Déconseillé |
| - | - |
| « Quelle est la perte de validation finale de mes 5 derniers runs ? » | « Comment se comporte mon modèle ? » |
| « Résume l’utilisation des jetons sur mes 10 dernières traces. » | « Montre-moi toutes mes traces. » |
| « Compare les configurations du run A et du run B. » | « Quels sont mes meilleurs runs ? » |
| « Quelle évaluation a obtenu le meilleur score F1 ? » | « Où en sont mes évaluations ? » |
serveur MCP Weights & Biases
Le Model Context Protocol (MCP) est une norme ouverte qui permet aux agents d’IA d’appeler des outils externes. Le serveur MCP Weights & Biases offre à votre IDE, à votre assistant de programmation ou à votre agent de chat un accès direct à vos données et à votre documentation Weights & Biases. Votre agent peut ainsi répondre à des questions sur vos runs, vos traces, vos évaluations et vos artifacts, sans avoir à copier-coller quoi que ce soit. Pour découvrir tout ce que vous pouvez faire avec le serveur, consultez la section [Fonctionnalités du serveur MCP Weights & Biases](#weights-&-biases-mcp-server-capabilities).
Types de déploiement
Le serveur MCP Weights & Biases est proposé selon deux options de déploiement. Utilisez le serveur hébergé pour une configuration plus rapide, ou configurez une version locale si vous avez besoin de davantage d’isolation et de flexibilité. Avec la version locale, votre client doit utiliser une autre URL pour accéder au serveur.
Un serveur MCP géré par Weights & Biases, auquel votre client se connecte via HTTP avec votre clé API. Aucune installation, aucun processus local à maintenir.
[Utiliser le serveur hébergé](#use-the-hosted-server)
Exécutez le serveur MCP sur votre propre machine via STDIO ou HTTP. Choisissez cette option si vous avez besoin d’un fonctionnement isolé du réseau, d’épingler une version précise ou de personnaliser le comportement du serveur, si vous développez activement le serveur, ou si votre client ne prend en charge que STDIO.
[Exécuter le serveur MCP en local](#run-the-mcp-server-locally)
Prérequis
Avant de configurer un client, assurez-vous de disposer des éléments suivants :
* Créez une clé API sur [forge.coreweave.com/settings#apikeys](https://forge.coreweave.com/settings#apikeys).
* Définissez la clé dans la variable d’environnement `WANDB_API_KEY`, ou transmettez-la à votre client sous forme de jeton Bearer.
* Pour le Cloud dédié, les déploiements autogérés et les installations locales qui utilisent une instance autre que celle par défaut, définissez la variable d’environnement `WANDB_BASE_URL` sur l’URL de votre instance.
* Weights & Biases épingle le SDK `mcp` à la version [1.14.0](https://pypi.org/project/mcp/1.14.0/), version `2024-11-05`. Les clients doivent se connecter avec le SDK `mcp` 1.14.x. Pour la prise en charge du transport HTTP en streaming (streamable HTTP) dans le Cloud dédié de W\&B, le SDK `mcp` 1.14.x en version `2025-03-26` ou ultérieure est requis.
Utiliser le serveur hébergé
Weights & Biases propose un serveur MCP géré pour chaque type de déploiement. Vous n’avez rien à installer. Configurez votre client pour qu’il se connecte en HTTP avec une clé API dans l’en-tête `Authorization`.
URL de connexion
L’URL dépend du type de déploiement Weights & Biases que vous utilisez :
| Déploiement | URL du serveur |
| - | - |
| Cloud mutualisé | `https://mcp.withwandb.com/mcp` |
| Cloud dédié | `https://[YOUR-INSTANCE]/mcp` |
| Autogéré | `https://[YOUR-INSTANCE]/mcp` |
Pour un déploiement Cloud dédié ou autogéré, remplacez `https://mcp.withwandb.com/mcp` par `https://[YOUR-INSTANCE]/mcp` sans rien modifier d’autre. Les configurations client ci-dessous utilisent l’URL du Cloud mutualisé.
Enregistrez le serveur MCP Weights & Biases dans Claude Code, en remplaçant le jeton Bearer par votre clé API :
```bash theme={"system"}
claude mcp add --transport http wandb https://mcp.withwandb.com/mcp \
--header "Authorization: Bearer [YOUR-WANDB-API-KEY]"
```
Ajoutez `--scope user` pour configurer Claude Code globalement. Omettez-le pour ne configurer que le projet actuel.
Vérifiez la connexion en demandant `List my W&B entities.` L’agent doit appeler `list_entities_tool` et renvoyer votre nom d’utilisateur ainsi que les éventuelles équipes dont vous faites partie. Si la connexion échoue, consultez la section [Dépannage](#troubleshooting). Pour plus d’informations, voir la [documentation MCP de Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp).
L'interface de connecteurs personnalisés intégrée à Claude Desktop ne prend pas en charge l'authentification par clé API pour les serveurs MCP distants. Pour contourner cette limitation, utilisez le proxy npm [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) afin de connecter Claude Desktop au serveur MCP distant de Weights & Biases. Le proxy s'exécute en local et transmet les requêtes à `https://mcp.withwandb.com/mcp` avec votre jeton Bearer.
[Node.js](https://nodejs.org/) doit être installé sur votre système.
Ouvrez le fichier de configuration de Claude Desktop dans un éditeur de texte. Selon votre système d'exploitation, ce fichier se trouve à l'emplacement suivant :
* **macOS** : `~/Library/Application\ Support/Claude/claude_desktop_config.json`
* **Windows** : `%APPDATA%\Claude\claude_desktop_config.json`
Ajoutez le contenu suivant à l'objet JSON de votre fichier de configuration, en remplaçant `[YOUR-WANDB-API-KEY]` par votre clé API :
```json theme={"system"}
{
"mcpServers": {
"wandb": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.withwandb.com/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer [YOUR-WANDB-API-KEY]"
}
}
}
}
```
La valeur complète de l’en-tête est définie via le champ `env` plutôt que directement dans `args`, afin de contourner un problème d’échappement des espaces qui affecte certaines versions de Claude Desktop.
Redémarrez Claude Desktop pour activer la nouvelle configuration. Vérifiez la connexion en posant la question `List my W&B entities.` L’agent doit appeler `list_entities_tool` et renvoyer votre nom d’utilisateur ainsi que vos éventuelles équipes. Si la connexion échoue, consultez la section [Dépannage](#troubleshooting).
Exportez votre clé API en tant que variable d’environnement, puis enregistrez le serveur auprès de Codex :
```bash theme={"system"}
export WANDB_API_KEY=[YOUR-WANDB-API-KEY]
codex mcp add wandb \
--url https://mcp.withwandb.com/mcp \
--bearer-token-env-var WANDB_API_KEY
```
Vérifiez la connexion en demandant `List my W&B entities.` L’agent doit appeler `list_entities_tool` et renvoyer votre nom d’utilisateur ainsi que les éventuelles équipes dont vous faites partie. Si la connexion échoue, consultez la section [Dépannage](#troubleshooting).
Installez automatiquement le serveur dans Cursor à l’aide du [lien d’installation en un clic](https://cursor.com/en/install-mcp?name=wandb\&config=eyJ0cmFuc3BvcnQiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9tY3Aud2l0aHdhbmRiLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIge3tXQU5EQl9BUElfS0VZfX0iLCJBY2NlcHQiOiJhcHBsaWNhdGlvbi9qc29uLCB0ZXh0L2V2ZW50LXN0cmVhbSJ9fQ%3D%3D), puis remplacez l’espace réservé par votre clé API dans le champ `Authorization`.
Pour configurer Cursor manuellement :
1. Sous macOS, ouvrez **Cursor** > **Settings** > **Cursor Settings**. Sous Windows ou Linux, ouvrez **Preferences** > **Settings** > **Cursor Settings**.
2. Sélectionnez **Tools and MCP**.
3. Dans **Installed MCP Servers**, sélectionnez **Add Custom MCP**. Cursor ouvre alors le fichier de configuration `mcp.json`.
4. Ajoutez le contenu suivant à l’objet `mcpServers` :
```json theme={"system"}
{
"mcpServers": {
"wandb": {
"transport": "http",
"url": "https://mcp.withwandb.com/mcp",
"headers": {
"Authorization": "Bearer [YOUR-WANDB-API-KEY]",
"Accept": "application/json, text/event-stream"
}
}
}
}
```
5. Redémarrez Cursor.
6. Vérifiez la connexion en saisissant la requête `List my W&B entities.` L’agent doit appeler `list_entities_tool` et renvoyer votre nom d’utilisateur ainsi que vos éventuelles équipes.
Si la connexion échoue, consultez la section [Dépannage](#troubleshooting). Pour plus d’informations, voir la [documentation MCP de Cursor](https://cursor.com/docs/context/mcp).
Installez l’extension MCP Weights & Biases :
```bash theme={"system"}
gemini extensions install https://github.com/wandb/wandb-mcp-server
```
Redémarrez Gemini CLI. Vérifiez la connexion en posant la question `List my W&B entities.` L’agent doit appeler `list_entities_tool` et renvoyer votre nom d’utilisateur ainsi que vos éventuelles équipes.
Si la connexion échoue, consultez la section [Dépannage](#troubleshooting). Pour plus d’informations, voir la [documentation MCP de Gemini CLI](https://geminicli.com/docs/tools/mcp-server/).
1. Dans LeChat, ouvrez le menu **Intelligence** et sélectionnez **Add Connector**.
2. Sélectionnez **Custom MCP Connector**.
3. Configurez les champs suivants :
* **Connector Server** : `https://mcp.withwandb.com/mcp`
* **Description** : (facultatif) une courte description.
* **Authentication Method** : sélectionnez **API Token Authentication**.
* **Header name** : conservez la valeur `Authorization`.
* **Header type** : sélectionnez **Bearer**.
* **Header value** : votre clé API.
4. Sélectionnez **Create**.
5. Vérifiez la connexion en demandant `List my W&B entities.` L’agent devrait appeler `list_entities_tool` et renvoyer votre nom d’utilisateur ainsi que vos éventuelles équipes.
Si la connexion échoue, consultez la section [Dépannage](#troubleshooting). Pour plus d'informations, voir la [documentation MCP de LeChat](https://mistral.ai/news/le-chat-mcp-connectors-memories).
Ajoutez le serveur au champ `tools` de votre appel d’API OpenAI Responses :
```python theme={"system"}
import os
from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
model="gpt-4o",
tools=[{
"type": "mcp",
"server_label": "wandb",
"server_description": "Query W&B data",
"server_url": "https://mcp.withwandb.com/mcp",
"authorization": os.getenv("WANDB_API_KEY"),
"require_approval": "never",
}],
input="List my W&B entities.",
)
print(resp.output_text)
```
Transmettez la clé API brute comme valeur de `authorization`. OpenAI ajoute le préfixe `Bearer ` lorsqu'il appelle le serveur ; ne l'incluez donc pas vous-même. L'intégration MCP d'OpenAI s'exécute côté serveur et ne peut donc pas accéder à un serveur MCP local. Pour le développement en local, consultez [Exécuter le serveur MCP en local](#run-the-mcp-server-locally).
Ouvrez votre fichier `mcp.json` global ou celui de votre espace de travail (par exemple, `~/.vscode/mcp.json` ou `.vscode/mcp.json`) et ajoutez-y le contenu suivant :
```json theme={"system"}
{
"servers": {
"wandb": {
"type": "http",
"url": "https://mcp.withwandb.com/mcp",
"headers": {
"Authorization": "Bearer [YOUR-WANDB-API-KEY]"
}
}
}
}
```
Redémarrez VS Code, vérifiez que le serveur apparaît dans le panneau MCP, puis testez la connexion en demandant `List my W&B entities.` L’agent doit appeler `list_entities_tool` et renvoyer votre nom d’utilisateur ainsi que vos éventuelles équipes.
Si la connexion échoue, consultez la section [Dépannage](#troubleshooting).
Exécuter le serveur MCP en local
Une installation locale est une alternative au serveur hébergé, et non l’option par défaut pour quelque type de déploiement que ce soit. Utilisez-la lorsque le serveur hébergé n’est pas adapté à votre configuration.
Raisons courantes d’une exécution en local :
* **Environnements isolés du réseau ou hors ligne**, dans lesquels votre client ne peut pas joindre un point de terminaison Weights & Biases hébergé.
* **Version épinglée**. Le serveur hébergé suit la branche principale. Une installation locale peut être épinglée sur un tag de version précis.
* **Comportement personnalisé du serveur**, par exemple pour modifier la description des outils, ajouter des outils ou définir un budget de jetons de réponse autre que celui par défaut.
* **Développement actif** du serveur lui-même.
* **Clients compatibles uniquement avec STDIO** ou clients qui nécessitent un processus local.
Si vous utilisez le Cloud dédié ou un déploiement autogéré, privilégiez l’option hébergée. N’utilisez une installation locale à partir de [wandb/wandb-mcp-server](https://github.com/wandb/wandb-mcp-server) que si le serveur hébergé n’est pas encore activé sur votre instance ou si l’une des raisons ci-dessus s’applique. Définissez la variable d’environnement `WANDB_BASE_URL` sur l’URL de votre instance.
Prérequis locaux
Pour exécuter le serveur localement, assurez-vous de disposer des éléments suivants :
* Python 3.11 ou version ultérieure.
* [`uv`](https://docs.astral.sh/uv/) ou `pip`.
* Une clé API, définie dans `WANDB_API_KEY`.
* La variable `WANDB_BASE_URL`, définie sur l’URL de votre instance si vous utilisez le Cloud dédié ou un déploiement autogéré.
Installer le serveur
Choisissez une méthode d’installation, puis exécutez la commande suivante pour installer le serveur MCP :
```bash theme={"system"}
uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server
```
```bash theme={"system"}
uv pip install wandb-mcp-server
```
```bash theme={"system"}
pip install wandb-mcp-server
```
```bash theme={"system"}
pip install git+https://github.com/wandb/wandb-mcp-server
```
Après avoir installé le serveur, configurez votre client pour qu’il le lance. Sélectionnez votre client MCP, puis appliquez la configuration suivante en remplaçant `[YOUR-WANDB-API-KEY]` par votre clé API si nécessaire :
Enregistrez le serveur local auprès de Claude Code. Ajoutez `--scope user` pour une configuration globale.
```bash theme={"system"}
claude mcp add wandb \
-e WANDB_API_KEY=[YOUR-WANDB-API-KEY] \
-e WANDB_BASE_URL=https://your-wandb-instance.example.com \
-- uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server
```
Ouvrez le fichier de configuration de Claude Desktop :
* **macOS** : `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows** : `%APPDATA%\Claude\claude_desktop_config.json`
Ajoutez le JSON suivant. Indiquez le chemin complet de `uvx`, sans quoi Claude Desktop risque de ne pas le trouver dans votre `PATH`.
```json theme={"system"}
{
"mcpServers": {
"wandb": {
"command": "/full/path/to/uvx",
"args": [
"--from",
"git+https://github.com/wandb/wandb-mcp-server",
"wandb_mcp_server"
],
"env": {
"WANDB_API_KEY": "[YOUR-WANDB-API-KEY]",
"WANDB_BASE_URL": "https://your-wandb-instance.example.com"
}
}
}
}
```
Redémarrez Claude Desktop pour appliquer la configuration.
```bash theme={"system"}
codex mcp add wandb \
--env WANDB_API_KEY=[YOUR-WANDB-API-KEY] \
--env WANDB_BASE_URL=https://your-wandb-instance.example.com \
-- uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server
```
Ajoutez le contenu suivant à votre configuration `mcp.json` :
```json theme={"system"}
{
"mcpServers": {
"wandb": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/wandb/wandb-mcp-server",
"wandb_mcp_server"
],
"env": {
"WANDB_API_KEY": "[YOUR-WANDB-API-KEY]",
"WANDB_BASE_URL": "https://your-wandb-instance.example.com"
}
}
}
}
```
Omettez `WANDB_BASE_URL` pour utiliser le point de terminaison par défaut de l’API W\&B.
Ajoutez le contenu suivant à votre fichier `.vscode/mcp.json` ou à votre configuration MCP globale :
```json theme={"system"}
{
"servers": {
"wandb": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/wandb/wandb-mcp-server",
"wandb_mcp_server"
],
"env": {
"WANDB_API_KEY": "[YOUR-WANDB-API-KEY]",
"WANDB_BASE_URL": "https://your-wandb-instance.example.com"
}
}
}
}
```
Exécuter le serveur avec le transport HTTP
Pour les clients web et les tests, exécutez le serveur avec le transport HTTP :
```bash theme={"system"}
uvx wandb_mcp_server --transport http --host 0.0.0.0 --port 8080
```
Pour exposer un serveur local à des clients externes, comme l’API Responses d’OpenAI, utilisez un tunnel :
```bash theme={"system"}
uvx wandb_mcp_server --transport http --port 8080
# Dans un autre terminal
ngrok http 8080
```
Mettez à jour la configuration de votre client MCP afin qu’il utilise l’URL du tunnel.
Variables d’environnement
Les variables d’environnement suivantes contrôlent l’authentification, l’acheminement vers l’instance et le comportement du serveur pour les installations locales. Définissez-les dans le bloc `env` de votre client ou exportez-les dans votre shell.
| Variable | Description |
| - | - |
| `WANDB_API_KEY` | Clé API pour l’authentification. Requise. |
| `WANDB_BASE_URL` | URL d’instance Weights & Biases personnalisée pour le Cloud dédié ou une installation autogérée. Par défaut : `https://api.wandb.ai`. |
| `WANDB_MCP_PROXY_DOCS` | Active le proxy de recherche dans la documentation `search_wandb_docs_tool`. Par défaut : `true`. |
| `WANDBOT_BASE_URL` | Point de terminaison personnalisé pour le proxy de recherche dans la documentation. |
| `MAX_RESPONSE_TOKENS` | Budget de jetons pour la troncature des réponses des outils. Par défaut : `30000`. |
| `MCP_SERVER_LOG_LEVEL` | Niveau de détail de la journalisation. Valeurs possibles : `DEBUG`, `INFO`, `WARNING`, `ERROR`. |
Pour la référence complète de la ligne de commande et les options avancées, consultez le [README de wandb-mcp-server](https://github.com/wandb/wandb-mcp-server#readme).
Fonctionnalités du serveur MCP Weights & Biases
Utilisez le serveur MCP pour analyser des expériences, déboguer des traces, créer des rapports, gérer le registre et les artifacts, et obtenir des réponses tirées de la documentation Weights & Biases. Les exemples de prompts suivants illustrent quelques-unes des tâches que vous pouvez confier à votre agent lorsqu’il est connecté au serveur MCP Weights & Biases :
* « Affiche les 5 meilleurs runs selon `eval/accuracy` dans `your-team/your-project`. »
* « Comment la latence des traces predict de mon agent de recrutement a-t-elle évolué au cours du dernier mois ? »
* « Génère un W\&B Report comparant les décisions prises par l’agent de recrutement la semaine dernière. »
* « Quelles sont les versions existantes de l’artifact `production-model`, et qu’est-ce qui a changé entre `v2` et `v3` ? »
* « Comment puis-je créer un leaderboard dans Weave ? »
Le serveur propose plusieurs outils, regroupés par usage. Le tableau suivant répertorie le nom de chaque outil, les situations dans lesquelles l’agent doit l’utiliser, ainsi qu’un exemple concret de prompt permettant de l’invoquer.
Outils permettant de découvrir les noms de projets et d’entity, et d’inspecter les schémas.
| Outil | Quand l’utiliser | Exemple de prompt |
| - | - | - |
| `list_entities_tool` | Aucun entity n’est spécifié, ou pour lister les équipes et les comptes accessibles avec la clé API. | « À quelles équipes Weights & Biases ai-je accès ? » |
| `query_wandb_entity_projects` | L’entity est connu, mais pas le nom du projet, ou une requête précédente a échoué avec l’erreur « project not found ». | « Liste tous les projets de `your-team`. » |
| `probe_project_tool` | Pour découvrir les métriques, les clés de configuration et les tags disponibles dans un projet basé sur des runs que vous ne connaissez pas. | « Analyse `your-team/your-project` et indique-moi quelles métriques sont journalisées. » |
| `infer_trace_schema_tool` | Pour découvrir les noms de champs, les types et des exemples de valeurs dans un projet de traces Weave que vous ne connaissez pas, avant de lancer une requête. | « Quels champs comportent les traces Weave de `your-team/your-project` ? » |
Outils permettant d’interroger, de comparer et de diagnostiquer les runs W\&B.
| Outil | Quand l’utiliser | Exemple de prompt |
| - | - | - |
| `query_wandb_tool` | La question porte sur des runs, des sweeps, des configurations, des résumés ou des artifacts dans Weights & Biases. Exécute une requête GraphQL. | "Affichez les 5 meilleurs runs selon `eval/accuracy` dans `your-team/your-project`." |
| `get_run_history_tool` | La question porte sur des courbes d’entraînement, l’évolution de métriques dans le temps ou toute série temporelle journalisée dans un run. | "Tracez la courbe de perte du run `abc123` dans `your-team/your-project`." |
| `compare_runs_tool` | La question porte sur ce qui a changé entre deux runs, ou vise à savoir lequel des deux est le meilleur. Renvoie le diff de configuration, le delta des métriques et, en option, l’historique aligné. | "Comparez les runs `abc123` et `def456` dans `your-team/your-project`." |
| `diagnose_run_tool` | La question est de savoir si un run a convergé, s’il est en surapprentissage ou s’il a rencontré des valeurs NaN. Renvoie des recommandations précises. | "Le run `abc123` dans `your-team/your-project` est-il en surapprentissage ?" |
Outils qui interrogent et agrègent les traces et les évaluations de LLM.
| Outil | Quand l’utiliser | Exemple de prompt |
| - | - | - |
| `query_weave_traces_tool` | Vous avez besoin des données de trace (appels LLM, évaluations, runs d’agent). Commencez par `detail_level="summary"` et ne passez à `"full"` que pour des traces précises. | "Affiche les traces en échec dans `your-team/your-project` au cours des dernières 24 heures." |
| `count_weave_traces_tool` | La question porte sur le nombre de traces ou d’erreurs, sans que les données de trace elles-mêmes soient nécessaires. | "Combien de traces ont échoué dans `your-team/your-project` cette semaine ?" |
| `resolve_trace_roots_tool` | Une fois que `query_weave_traces_tool` a trouvé des traces enfants, pour rattacher chacune à sa session ou à son flux de travail racine en un seul appel groupé. | "Trouve les appels LLM qui contiennent `rate limit` et indique-moi à quelles sessions ils appartiennent." |
| `summarize_evaluation_tool` | La question porte sur le déroulement d’une évaluation, son taux de réussite ou les tâches qui échouent le plus souvent. Agrège les hiérarchies `Evaluation.evaluate`. | "Résume l’évaluation la plus récente dans `your-team/your-project`." |
Outils qui enregistrent les analyses dans Weights & Biases.
| Outil | Quand l’utiliser | Exemple de prompt |
| - | - | - |
| `create_wandb_report_tool` | L’utilisateur demande explicitement de créer un rapport ou d’enregistrer des constats. Accepte du Markdown ainsi qu’un tableau `panels` pour des graphiques en courbes, des graphiques à barres et des comparaisons de runs. | « Créez un rapport W\&B comparant les runs `abc123` et `def456`. » |
| `log_analysis_to_wandb` | Des valeurs calculées dans la session MCP (distributions de latence, répartition des erreurs) doivent être enregistrées sous forme de run avant de pouvoir être référencées dans un rapport. | « Journalisez ces centiles de latence dans Weights & Biases sous forme de run d’analyse. » |
Outils permettant d’inspecter et de comparer des modèles, des datasets et d’autres artifacts versionnés.
| Outil | Quand l’utiliser | Exemple de prompt |
| - | - | - |
| `list_registries_tool` | La question porte sur les registres de modèles, les modèles enregistrés ou les datasets enregistrés d’une organisation. | "Quels sont les registres de `your-org` ?" |
| `list_registry_collections_tool` | Pour savoir quels modèles ou datasets se trouvent dans un registre donné. | "Quelles collections contient le registre `model` de `your-org` ?" |
| `list_artifact_versions_tool` | Pour lister les versions disponibles d’un modèle, d’un dataset ou d’une autre collection d’artifacts. | "Liste les versions de `production-model` dans `your-team/your-project`." |
| `get_artifact_details_tool` | Pour inspecter une version d’artifact précise, y compris sa traçabilité et ses fichiers. | "Que contient `production-model:v3` ?" |
| `compare_artifact_versions_tool` | La question porte sur les modifications entre deux versions d’artifact. | "Compare `production-model:v2` et `production-model:v3`." |
Outils permettant de répondre aux questions sur les produits en s’appuyant sur la documentation officielle de Weights & Biases.
| Outil | Quand l’utiliser | Exemple de prompt |
| - | - | - |
| `search_wandb_docs_tool` | La question porte sur l’utilisation d’une fonctionnalité ou d’une API de Weights & Biases ou de Weave. Sert de proxy vers [docs.wandb.ai](/fr/forge-home). | « Comment puis-je créer un leaderboard dans Weave ? » |
Requêtes de traces guidées par le schéma
Pour les requêtes de traces Weave, appelez d’abord `infer_trace_schema_tool` afin de découvrir les champs disponibles, puis appelez `query_weave_traces_tool` avec une liste de colonnes précise et un `detail_level` :
| `detail_level` | Renvoie | Cas d’utilisation |
| - | - | - |
| `schema` | Champs structurels uniquement. Le plus rapide. | Exploration ou comptage. |
| `summary` | Entrées et sorties tronquées. Valeur par défaut. | La plupart des tâches d’analyse. |
| `full` | Tout, sans troncature. | Analyse approfondie d’un petit nombre de traces précises. |
Cette approche limite l’utilisation des jetons pour les questions générales et permet à l’agent de passer à `full` uniquement pour les traces pertinentes.
Conseils d’utilisation
Les sections suivantes décrivent des pratiques et des flux de travail qui vous aideront à obtenir de meilleurs résultats avec le serveur MCP Weights & Biases. Commencez par les pratiques générales, puis consultez la section adaptée à votre charge de travail pour obtenir des conseils plus précis et des enchaînements d’outils en plusieurs étapes.
Bonnes pratiques générales
Suivez ces pratiques quel que soit votre cas d’usage :
* **Précisez l’entity et le projet.** Les outils MCP nécessitent une entity explicite (votre équipe ou votre compte personnel) et un nom de projet. Indiquez-les tous les deux dans chaque question, par exemple « dans `your-team/your-project` ».
* **Posez des questions ciblées.** Préférez « Quelle évaluation a obtenu le meilleur score F1 ? » à « Quelle est ma meilleure évaluation ? ». Des métriques et des plages temporelles précises donnent lieu à de meilleurs appels d’outils.
* **Vérifiez que la récupération est complète.** Pour les questions générales telles que « Quels sont mes runs les plus performants ? », demandez à l’agent de confirmer qu’il a bien récupéré tous les runs disponibles, et pas uniquement les plus récents.
* **Associez-le à W\&B Skills.** [W\&B Skills](#w\&b-skills) apprend aux agents de développement à structurer les flux de travail Weights & Biases. Les Skills fournissent des modèles, MCP donne accès aux données : les deux se complètent parfaitement.
Pour les flux de travail riches en traces
Suivez ces bonnes pratiques lorsque vous travaillez avec les traces Weave :
* **Commencez par le schéma.** Appelez `infer_trace_schema_tool` avant `query_weave_traces_tool` afin de fournir à l’agent les champs et les valeurs de filtre valides.
* **Choisissez le bon `detail_level`.** Utilisez `schema` pour parcourir les données, `summary` (la valeur par défaut) pour l’analyse, et `full` uniquement pour examiner en détail un petit nombre de traces précises.
* **Enchaînez avec `resolve_trace_roots_tool`.** Après une requête sur des traces enfants, transmettez la liste de `trace_id` obtenue à `resolve_trace_roots_tool` pour associer chaque trace à sa session racine en un seul appel par lot.
* **Privilégiez `summarize_evaluation_tool` pour les évaluations.** Cet outil agrège automatiquement la hiérarchie `Evaluation.evaluate` et `predict_and_score`. Ne revenez à `query_weave_traces_tool` que pour obtenir les données de trace brutes.
Pour un flux de travail de bout en bout, consultez [Analyser les appels LLM en échec](#triage-failing-llm-calls).
Pour les flux de travail centrés sur les runs
Suivez ces bonnes pratiques lorsque vous travaillez avec des runs W\&B :
* **Sondez avant d’interroger.** Appelez `probe_project_tool` sur un projet basé sur des runs que vous ne connaissez pas afin de découvrir les clés de métriques, les clés de configuration et les tags avant de rédiger une requête GraphQL.
* **Utilisez `get_run_history_tool` pour les séries temporelles.** GraphQL n’effectue pas d’échantillonnage : pour les courbes de perte et les autres séries temporelles, `get_run_history_tool` est donc à la fois plus rapide et moins coûteux.
* **Confiez la comparaison à `compare_runs_tool`.** Il renvoie les écarts de configuration et de métriques, avec un historique aligné, en un appel unique, ce qui vous évite toute comparaison manuelle.
* **Commencez par un contrôle de santé.** Lorsqu’un run d’entraînement semble anormal, appelez `diagnose_run_tool` avant d’examiner manuellement l’historique.
Pour des flux de travail de bout en bout, consultez [Diagnostiquer un run d’entraînement défaillant](#diagnose-a-bad-training-run) et [Synthétiser les évaluations et comparer les versions de modèles](#summarize-evals-and-compare-model-versions).
Pour le Cloud dédié et les déploiements autogérés
Appliquez ces bonnes pratiques pour les déploiements non mutualisés :
* Privilégiez le serveur hébergé sur votre instance à l’adresse `https://[YOUR-INSTANCE]/mcp`. Il expose les mêmes outils que le serveur multilocataire, sans qu’il soit nécessaire de définir `WANDB_BASE_URL` côté client. N’optez pour une installation locale que si le serveur hébergé n’est pas encore activé.
* Si vous exécutez le serveur localement en le connectant à votre instance, définissez `WANDB_BASE_URL` sur l’URL de votre instance dans le bloc `env` du client. Sans cela, le serveur cible `api.wandb.ai` et ne renvoie aucune donnée.
* Les limites de débit du Cloud dédié sont distinctes de celles du Cloud mutualisé. Consultez [Limites de débit du Cloud dédié](/fr/products/wandb/platform/hosting/hosting-options/dedicated-cloud/rate-limits) pour connaître les valeurs par défaut et la procédure à suivre pour demander une modification.
Pour les installations locales
Suivez ces bonnes pratiques lorsque vous exécutez le serveur sur votre propre machine :
* Privilégiez le transport STDIO pour les clients de bureau (Cursor, VS Code, Claude Code, Claude Desktop). Ne passez au transport HTTP que si un client l’exige explicitement (par exemple, l’API Responses d’OpenAI).
* Si des appels d’outil échouent sans signaler d’erreur, définissez `MCP_SERVER_LOG_LEVEL=DEBUG` dans le bloc `env` du client, puis vérifiez de nouveau les journaux MCP du client.
* Si vous effectuez l’installation depuis GitHub (`uvx --from git+https://github.com/wandb/wandb-mcp-server wandb_mcp_server`), `uvx` utilise par défaut la branche principale du dépôt. Si vous avez besoin d’une version stable, épinglez un tag précis en ajoutant `@v0.3.2` à l’URL Git.
Flux de travail recommandés
La plupart des questions concrètes font appel à plusieurs outils. Les flux de travail suivants présentent des enchaînements d’outils courants, en plusieurs étapes, que vous pouvez confier à votre agent.
Explorer un projet inconnu
Pour explorer ce qui a été journalisé dans un projet, enchaînez ces outils :
1. `list_entities_tool` pour trouver une entity ou une équipe.
2. `query_wandb_entity_projects` pour trouver le projet.
3. `probe_project_tool` pour les projets basés sur des runs, ou `infer_trace_schema_tool` pour les projets de traces Weave.
4. Un appel ciblé à `query_wandb_tool` ou à `query_weave_traces_tool` avec les clés identifiées.
Analyser les appels LLM en échec
Pour trouver les traces défaillantes et les sessions dont elles proviennent, enchaînez ces outils :
1. `query_weave_traces_tool` avec un filtre sur les champs d’erreur ou d’exception, et `detail_level="summary"`.
2. `resolve_trace_roots_tool` sur la liste de `trace_id` obtenue, afin de rattacher chaque échec à sa session racine.
3. `query_weave_traces_tool` avec `detail_level="full"` sur quelques racines ciblées, pour les examiner en détail.
4. `create_wandb_report_tool` pour documenter les constats.
Diagnostiquer un run d’entraînement défaillant
Pour effectuer un contrôle de santé sur un run d’entraînement suspect, enchaînez ces outils :
1. `get_run_history_tool` pour récupérer les courbes de perte et de validation.
2. `diagnose_run_tool` pour vérifier automatiquement la convergence, le surapprentissage et la présence de valeurs NaN.
3. `compare_runs_tool` pour comparer le run à un run de référence dont la fiabilité est établie.
4. `create_wandb_report_tool` avec des panneaux de graphiques linéaires pour partager le diagnostic.
Résumer les évaluations et comparer les versions de modèle
Pour trouver la version de modèle la plus performante à une évaluation, enchaînez ces outils :
1. `summarize_evaluation_tool` pour obtenir les taux de réussite et le nombre d’erreurs par évaluateur.
2. `list_artifact_versions_tool` sur la collection de modèles concernée.
3. `compare_artifact_versions_tool` entre la version candidate et la version actuellement en production.
4. `log_analysis_to_wandb` et `create_wandb_report_tool` pour publier la comparaison.
Dépannage
Utilisez le tableau suivant pour diagnostiquer et résoudre les problèmes rencontrés avec le serveur MCP Weights & Biases :
| Symptôme | Cause et solution |
| - | - |
| `401 Unauthorized` ou `Invalid API key` | Votre clé API est manquante, mal formée ou non autorisée pour l’entity ou l’équipe cible. Générez une nouvelle clé sur [forge.coreweave.com/settings#apikeys](https://forge.coreweave.com/settings#apikeys) et vérifiez qu’elle est transmise en tant que jeton Bearer ou définie dans `WANDB_API_KEY`. |
| Résultats vides pour des requêtes censées aboutir | Le nom de l’équipe, de l’entity ou du projet est incorrect, ou la clé API n’y a pas accès. Vérifiez ces deux points avec l’agent, puis réessayez. |
| `404 Not Found` ou `connection refused` sur `https://[YOUR-INSTANCE]/mcp` | Le serveur MCP hébergé n’est pas encore activé sur votre instance Cloud dédié ou autogérée, ou le client pointe vers une mauvaise URL. Contactez l’[assistance Weights & Biases](mailto:forge-support@coreweave.com) pour demander son activation, puis vérifiez l’URL indiquée dans la section [URL de connexion](#connection-url). |
| `429 Too Many Requests` sur Cloud dédié | Vous avez atteint les limites de débit de votre instance. Consultez [Limites de débit du Cloud dédié](/fr/products/wandb/platform/hosting/hosting-options/dedicated-cloud/rate-limits) pour savoir comment demander un relèvement de ces limites. |
| Le serveur local ne trouve pas `uvx` dans Claude Desktop | Indiquez le chemin complet de `uvx` dans le champ `command` de `claude_desktop_config.json`. |