Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications, à vos environnements de QA, de préproduction ou de production, ou à des sources pour lesquelles vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni l'évasion de protections anti-robot.
Un data loader LlamaIndex qui rencontre un défi CAPTCHA ne « plante » pas toujours : il rapatrie la page interstitielle, l'indexe comme du contenu, et votre index RAG se remplit de bruit. La correction tient en trois gestes : détecter la page de défi avant l'indexation, obtenir un token via l'API CaptchaAI, rejouer la requête dans la même session. Ce guide décrit cette intégration côté serveur et les garde-fous qui la rendent tenable sur un ordonnanceur nocturne.
Où le CAPTCHA apparaît dans un pipeline d'ingestion
Le défi surgit rarement au premier appel : la source applique d'abord une limitation de débit, puis présente un Cloudflare Turnstile ou un reCAPTCHA v2 au client HTTP. Trois symptômes le trahissent avant même les logs : des documents de longueur anormalement homogène, un taux de nœuds vides qui grimpe, un coût d'embedding stable alors que le volume utile s'effondre.
La règle de conception qui en découle : votre Reader ne transmet jamais au parser une réponse dont il n'a pas validé la nature. Une assertion simple suffit (sélecteur attendu, longueur minimale, absence de marqueur de défi) ; la résolution CAPTCHA se branche sur cet échec, pas sur le chemin nominal.
Architecture cible : le loader appelle, CaptchaAI répond
Le composant d'ingestion appelle CaptchaAI en HTTPS, récupère un token et l'injecte dans la requête d'origine. Aucun secret ne circule vers le navigateur, aucune dépendance n'est ajoutée à LlamaIndex : la résolution vit dans un module utilitaire.
Trois principes rendent cette architecture stable :
- Une seule session. Appliquez le token dans le contexte qui a déclenché le défi — mêmes cookies, même client HTTP. Un token rejeté vient le plus souvent d'une session dépareillée.
- Un budget de temps borné. Attendez une quinzaine de secondes avant la première interrogation, puis interrogez toutes les 5 secondes, avec un plafond de 120 secondes par tâche.
- Un point d'entrée unique. Centralisez l'appel : c'est cette fonction que vous instrumenterez et remplacerez le jour où le type de défi change.
Ce que CaptchaAI prend en charge dans ce contexte
Les types utiles à un pipeline d'ingestion sont couverts en disponibilité générale : reCAPTCHA v2 (y compris Invisible et Enterprise), reCAPTCHA v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, les CAPTCHA image/OCR et les grilles d'images. CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) restent à traiter comme des types en bêta dans vos tests. En revanche, hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge, et GeeTest v4 est annoncé comme à venir.
La facturation est basée sur les threads, avec des résolutions illimitées par thread : BASIC ($15/mois, 5 threads) suffit à un lot nocturne séquentiel, STANDARD ($30/mois, 15 threads) à une ingestion sur une quinzaine de workers, ADVANCE ($90/mois, 50 threads) à un crawl large. Calez le nombre de threads sur votre parallélisme réel, pas sur votre volume.
Exemple de code
Exemple d'appel HTTP côté serveur dans votre propre service :
import fetch from 'node-fetch';
const API_KEY = process.env.CAPTCHAAI_KEY;
export async function createTurnstileTask(siteKey, pageUrl) {
const res = await fetch('https://api.captchaai.com/createTask', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
clientKey: API_KEY,
task: {
type: 'TurnstileTaskProxyless',
websiteURL: pageUrl,
websiteKey: siteKey,
},
}),
});
const data = await res.json();
return data.taskId;
}
Côté LlamaIndex, appelez cette fonction depuis le gestionnaire d'échec du loader : le document n'entre dans l'index qu'une fois la requête rejouée avec succès.
Secrets, hébergement et RGPD
La clé CaptchaAI vit dans un coffre (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault) ou dans un secret d'intégration continue ; le déploiement la monte en variable d'environnement au runtime. Elle n'a rien à faire dans un notebook ni dans les métadonnées d'un document indexé.
Pour une équipe européenne, le placement compte autant que le stockage : un worker chez OVHcloud, Scaleway ou en région AWS eu-west-3 (Paris) garde la latence sous contrôle et simplifie la cartographie des traitements. Côté RGPD, appliquez la minimisation à l'ingestion elle-même — ne conservez pas le HTML brut des pages de défi, purgez les cookies en fin de lot, fixez une rétention pour les logs contenant des URL. La facturation reste en dollars US.
Observabilité et journalisation
Instrumentez chaque appel : durée d'obtention du token, code retour HTTP, identifiant de tâche, taille de la file d'attente. Ces signaux alimentent tableaux de bord et alertes.
| Indicateur | Ce qu'il révèle | Seuil de vigilance |
|---|---|---|
| Temps de résolution médian | Santé de l'intégration | Dérive de plus de 50 % sur 24 h |
| Taux de réussite par famille | Justesse des paramètres envoyés | Baisse soudaine sur un seul type |
| Écart résolution / acceptation | Token appliqué hors session | Quelques points d'écart |
| Nouvelles tentatives par lot | Boucles de retry masquées | Hausse à volume constant |
Séparez les journaux par environnement et corrélez les identifiants avec votre traçage distribué (OpenTelemetry, par exemple) : vous rejouerez un lot entier depuis un identifiant unique, et le diagnostic s'accélère.
Liste de contrôle avant mise en production
- Périmètre limité à vos applications ou à des sources autorisées.
- Le loader détecte une page de défi avant de l'envoyer au parser.
- La clé CaptchaAI est dans un coffre ou un secret CI, jamais dans le code source.
- Durées d'appel et codes retour tracés à chaque exécution.
- Retry idempotent plafonné sur les erreurs transitoires.
- Tests d'intégration rejouables depuis votre chaîne CI.
FAQ
CaptchaAI prend-il en charge hCaptcha dans un pipeline LlamaIndex ?
Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs). Si une source autorisée bascule sur ces familles, retirez-la du lot et documentez l'exclusion. GeeTest v4 est annoncé comme à venir ; GeeTest v3 est disponible.
Quel plan choisir pour une ingestion nocturne ?
Dimensionnez sur votre parallélisme, pas sur votre volume. Un lot séquentiel tient sur BASIC ($15/mois, 5 threads) ; une quinzaine de workers simultanés appelle STANDARD ($30/mois, 15 threads). Les résolutions étant illimitées par thread, un lot plus long occupe le thread plus longtemps mais ne coûte pas plus cher.
Peut-on réutiliser un token d'une exécution à l'autre ?
Non. Un token a une durée de vie courte et reste lié à la session qui a déclenché le défi. Résolvez à la demande, dans le même client HTTP, et jetez le token dès la requête rejouée : tout stockage anticipé fragilise l'intégration et fausse vos métriques.
Comment rester conforme au RGPD quand le loader collecte des pages ?
Traitez l'ingestion comme un traitement à part entière : minimisez les données collectées, excluez les pages portant des données personnelles inutiles à votre index, fixez une rétention pour les logs d'URL, tracez la base juridique de chaque source. Validez ces points avec votre référent conformité.
Guides connexes
- Le démarrage rapide CaptchaAI
- Résoudre un CAPTCHA en environnement de test autorisé
- Tester l'endpoint de résolution sur vos formulaires
- Intégrer la résolution CAPTCHA à votre chaîne CI
- Résoudre reCAPTCHA v2 via l'API
Vos loaders méritent un index propre plutôt que des pages de défi indexées par erreur. – Obtenez votre clé CaptchaAI.
