Filtrage des domaines pour la recherche sur le Web

Le filtrage des domaines permet à un administrateur d'organisation de contrôler les sites Web auxquels Mistral peut accéder pour le compte de votre organisation. Vous définissez une liste de domaines et une action par défaut. Mistral les applique aux résultats de recherche sur le Web, aux requêtes open_url et aux explorations de sites Web dans les bibliothèques.

Utilisez-le pour limiter un agent à un ensemble de sources fiables ou pour exclure certains sites de vos résultats.

Deux modes sont disponibles :

• Liste d'autorisation : bloque tous les domaines sauf ceux que vous indiquez.
• Liste de blocage : autorise tous les domaines sauf ceux que vous indiquez.

Le filtrage supprime uniquement des résultats. Il n'ajoute jamais de résultat que la recherche sur le Web n'aurait pas renvoyé autrement.

Vous avez besoin des éléments suivants :

• Une organisation sur la plateforme Mistral cloud (api.mistral.ai).
• Une clé API appartenant à cette organisation. Si la clé est liée à un compte utilisateur, cet utilisateur doit avoir le rôle d'administrateur de l'organisation. Consultez Rôles et autorisations.
• Un terminal ou un client HTTP.

Tous les endpoints de cette page se trouvent sous https://api.mistral.ai/v1/web-filters. Le panneau d'administration ne propose pas encore de page pour le filtrage des domaines. La configuration se fait donc uniquement via l'API. Ces endpoints ne sont pas encore disponibles dans les bibliothèques clientes Mistral. Les exemples utilisent donc curl.

Définissez votre clé une seule fois :

export MISTRAL_API_KEY="your-api-key"

export MISTRAL_API_KEY="your-api-key"

Le filtrage des domaines est un contrôle de gouvernance appliqué aux outils Mistral qui accèdent au Web. Il ne contrôle pas l'accès sortant au niveau du réseau et ne couvre pas tous les moyens par lesquels un modèle peut accéder au Web.

Les listes de votre organisation s'appliquent aux éléments suivants :

• Résultats de web_search dans l'API Conversations et l'API Agents, y compris dans web_search_premium et lors des transferts entre agents.
• open_url, qui récupère une page à partir de son URL. Une requête visant un domaine bloqué par vos listes est refusée au lieu de récupérer la page.
• Bibliothèques de sites Web, qui explorent un site de votre choix. L'exploration d'un domaine bloqué est refusée lors de l'enregistrement de la bibliothèque, puis à nouveau au démarrage d'une exploration.

Deux étapes : choisissez un mode, puis ajoutez des domaines.

Définissez le blocage comme action par défaut, puis indiquez les domaines à autoriser.

curl --request PUT "https://api.mistral.ai/v1/web-filters/config" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"block_by_default": true}'

curl --request PUT "https://api.mistral.ai/v1/web-filters/config" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"block_by_default": true}'

curl --request POST "https://api.mistral.ai/v1/web-filters/domains/allowed" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"domains": ["reuters.com", "arxiv.org", "docs.mistral.ai"]}'

curl --request POST "https://api.mistral.ai/v1/web-filters/domains/allowed" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"domains": ["reuters.com", "arxiv.org", "docs.mistral.ai"]}'

Réponse :

{
  "domains": ["reuters.com", "arxiv.org", "docs.mistral.ai"]
}

{
  "domains": ["reuters.com", "arxiv.org", "docs.mistral.ai"]
}

La recherche sur le Web renvoie désormais uniquement des résultats provenant de ces trois domaines et de leurs sous-domaines.

Définissez l'autorisation comme action par défaut, puis indiquez les domaines à bloquer.

curl --request PUT "https://api.mistral.ai/v1/web-filters/config" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"block_by_default": false}'

curl --request PUT "https://api.mistral.ai/v1/web-filters/config" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"block_by_default": false}'

curl --request POST "https://api.mistral.ai/v1/web-filters/domains/blocked" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"domains": ["example-competitor.com", "low-quality-aggregator.net"]}'

curl --request POST "https://api.mistral.ai/v1/web-filters/domains/blocked" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"domains": ["example-competitor.com", "low-quality-aggregator.net"]}'

La recherche sur le Web renvoie désormais des résultats de tous les domaines, à l'exception de ces deux domaines et de leurs sous-domaines.

Votre organisation dispose d'un paramètre et de deux listes.

Tant que vous n'appelez pas PUT /config, votre organisation n'a aucune configuration et aucun filtrage ne s'applique. Dans cet état, GET /config renvoie null :

curl "https://api.mistral.ai/v1/web-filters/config" \
     --header "Authorization: Bearer $MISTRAL_API_KEY"

curl "https://api.mistral.ai/v1/web-filters/config" \
     --header "Authorization: Bearer $MISTRAL_API_KEY"

{
  "block_by_default": null
}

{
  "block_by_default": null
}

Les deux listes sont toujours consultées, dans les deux modes. Vous pouvez ainsi définir des exceptions à une règle générale. Par exemple, avec block_by_default: false, vous pouvez bloquer example.com tout en autorisant blog.example.com.

Chaque opération ci-dessous est disponible pour chacune des deux listes : utilisez /domains/allowed pour votre liste d'autorisation et /domains/blocked pour votre liste de blocage. Les exemples présentent une liste à la fois. L'autre fonctionne de la même manière.

curl "https://api.mistral.ai/v1/web-filters/domains/blocked" \
     --header "Authorization: Bearer $MISTRAL_API_KEY"

curl "https://api.mistral.ai/v1/web-filters/domains/blocked" \
     --header "Authorization: Bearer $MISTRAL_API_KEY"

{
  "domains": ["example-competitor.com", "low-quality-aggregator.net"]
}

{
  "domains": ["example-competitor.com", "low-quality-aggregator.net"]
}

Renvoie 404 si le domaine ne figure pas dans cette liste.

curl "https://api.mistral.ai/v1/web-filters/domains/blocked/example-competitor.com" \
     --header "Authorization: Bearer $MISTRAL_API_KEY"

curl "https://api.mistral.ai/v1/web-filters/domains/blocked/example-competitor.com" \
     --header "Authorization: Bearer $MISTRAL_API_KEY"

{
  "domain": "example-competitor.com"
}

{
  "domain": "example-competitor.com"
}

Envoyez entre 1 et 1 000 domaines par requête. Une requête qui ne respecte pas cette plage renvoie 422. L'ajout d'un domaine déjà présent dans la liste réussit sans rien modifier. Vous pouvez donc relancer une requête sans risque.

curl --request POST "https://api.mistral.ai/v1/web-filters/domains/allowed" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"domains": ["nature.com", "science.org"]}'

curl --request POST "https://api.mistral.ai/v1/web-filters/domains/allowed" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"domains": ["nature.com", "science.org"]}'

La réponse indique les domaines présents dans cette liste après la requête, sous leur forme enregistrée.

Supprimez un domaine. La réponse est 204 No Content. La suppression d'un domaine absent de la liste renvoie également 204.

curl --request DELETE "https://api.mistral.ai/v1/web-filters/domains/allowed/nature.com" \
     --header "Authorization: Bearer $MISTRAL_API_KEY"

curl --request DELETE "https://api.mistral.ai/v1/web-filters/domains/allowed/nature.com" \
     --header "Authorization: Bearer $MISTRAL_API_KEY"

Supprimez plusieurs domaines à la fois avec batch-delete, qui renvoie également 204 :

curl --request POST "https://api.mistral.ai/v1/web-filters/domains/allowed/batch-delete" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"domains": ["nature.com", "science.org"]}'

curl --request POST "https://api.mistral.ai/v1/web-filters/domains/allowed/batch-delete" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"domains": ["nature.com", "science.org"]}'

Les entrées des deux listes sont prises en compte quelle que soit l'action par défaut. Changer de mode ne suffit donc pas. Un domaine qui reste dans la liste de blocage continue d'être exclu. Pour arrêter le filtrage sans supprimer votre liste d'autorisation, effectuez les deux étapes suivantes.

Définissez l'autorisation comme action par défaut :

curl --request PUT "https://api.mistral.ai/v1/web-filters/config" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"block_by_default": false}'

curl --request PUT "https://api.mistral.ai/v1/web-filters/config" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"block_by_default": false}'

Consultez la liste de blocage, puis videz-la :

curl "https://api.mistral.ai/v1/web-filters/domains/blocked" \
     --header "Authorization: Bearer $MISTRAL_API_KEY"

curl "https://api.mistral.ai/v1/web-filters/domains/blocked" \
     --header "Authorization: Bearer $MISTRAL_API_KEY"

curl --request POST "https://api.mistral.ai/v1/web-filters/domains/blocked/batch-delete" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"domains": ["example-competitor.com", "low-quality-aggregator.net"]}'

curl --request POST "https://api.mistral.ai/v1/web-filters/domains/blocked/batch-delete" \
     --header "Authorization: Bearer $MISTRAL_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{"domains": ["example-competitor.com", "low-quality-aggregator.net"]}'

Envoyez un nom d'hôte seul. Mistral normalise la valeur envoyée avant de l'enregistrer. Une URL complète est donc également acceptée.

Deux règles en découlent :

• Le préfixe www. est conservé. example.com et www.example.com sont deux entrées distinctes.
• Les domaines internationalisés sont convertis au format punycode. Les entrées correspondent ainsi aux noms d'hôte résolus par un navigateur.

L'API renvoie 422 pour toute valeur qui n'est pas un nom d'hôte valide, notamment les adresses IP seules, les noms d'hôte sans domaine de premier niveau et ceux contenant un label invalide.

Une entrée correspond au domaine lui-même et à tous ses sous-domaines. example.com correspond à example.com, news.example.com et a.b.example.com.

Pour cibler un sous-domaine précis, ajoutez-le comme entrée distincte.

Lorsque le nom d'hôte d'un résultat correspond à des entrées des deux listes, la correspondance la plus longue l'emporte. L'action par défaut ne s'applique que si aucune entrée ne correspond.

Exemple avec block_by_default: false, example.com bloqué et blog.example.com autorisé :

Un résultat filtré est exclu avant la construction de la réponse. Il n'est ni renvoyé, ni cité, ni visible par le modèle. Aucun élément ne le remplace et aucun décompte des résultats supprimés n'est fourni.

Trois points à connaître :

• Le filtrage s'exécute avant l'application de la limite de résultats. Un résultat exclu n'est pas comptabilisé dans le nombre de résultats demandé. Une recherche peut donc toujours renvoyer une page complète après filtrage.
• Un résultat dont l'URL est inutilisable suit l'action par défaut. Si le nom d'hôte d'un résultat ne peut pas être lu, le résultat est exclu en mode liste d'autorisation et conservé en mode liste de blocage.
• Le filtrage n'élargit jamais les résultats. Il peut uniquement supprimer des résultats déjà trouvés par la recherche sur le Web.

Une recherche renvoie de nombreux résultats. Les résultats filtrés sont donc supprimés sans notification. En revanche, une requête visant un seul domaine est refusée, ce qui permet d'en indiquer la raison à l'appelant.

Les deux renvoient 451 Unavailable For Legal Reasons :

• open_url indique que les filtres de votre organisation ont bloqué la page. Ce cas est distinct de celui où le site est inaccessible.
• Les bibliothèques de sites Web refusent le domaine lors de l'enregistrement de la bibliothèque, puis à nouveau au démarrage d'une exploration. Une bibliothèque enregistrée avant le blocage de son domaine cesse de l'explorer dès l'exécution suivante.

• Pour connaître les outils de recherche sur le Web et savoir comment les appeler, consultez Recherche sur le Web.
• Pour connaître les rôles permettant d'administrer une organisation, consultez Rôles et autorisations.