00. Spécification — Kit RAG Google Drive sur GCP (RAG Engine + synchro)

Statut : validée le 14/10/2026 · Sous-projet : 1 / 3 de gcp_rag Projet de test : main-project-511608 (compte Gmail, sans organisation)

1. Le besoin

« J'arrive, je donne mon dossier Drive, et j'ai un RAG performant dessus, mis à jour automatiquement. Je peux aussi déposer des documents par glisser-déposer. Plus tard : OneDrive, SharePoint. »

Hors périmètre (volontaire) : droits par utilisateur (chacun ne voit que ses documents) → sous-projet 2 (Gemini Enterprise natif). Ici, toute personne qui a accès à l'interface interroge tout le corpus.

2. Architecture

  Dossier(s) Google Drive                     Navigateur (vous, collègues)
  partagé(s) en lecture avec :                      │  gcloud run services proxy
   • rag-kit-sa@…   (liste, détecte suppressions)   ▼
   • service-N@gcp-sa-vertex-rag… (importe)   ┌──────────────────────────────────────┐
        │                                     │ Cloud Run « rag-kit » (privé)          │
        │                                     │  FastAPI : API ADK + /api/* + page web │
        │                                     │  Agent ADK « assistant_documents »     │
        │                                     │  (Gemini 2.5 Flash, outil de recherche)│
        │                                     └───┬─────────────┬──────────────┬──────┘
        │                         dépôt de fichier │  lance le job │  recherche   │
        │                          ▼               │               ▼              ▼
        │                   GCS  gs://…-rag-kit    │      Cloud Run job    RAG Engine
        │                    uploads/ · config.json└────► « rag-kit-sync » ─► corpus « rag-kit »
        └─────────────────────────────────────────────────▲  (RagManagedDb, europe-west4)
                                      Cloud Scheduler ────┘  */10 * * * *
                                                              Document AI layout parser (eu)

Une seule image sert au service (interface + agent) et au job (synchro) ; seule la commande change.

3. Composants

3.1 Synchro (le cœur) — algorithme

Une passe, idempotente, sûre à relancer :

1. Lire config.json (liste des dossiers Drive) dans le bucket.
2. Souhaité = fichiers Drive (récursif, hors corbeille, types supportés) de chaque dossier + objets gs://BUCKET/uploads/**.
3. Présent = list_files(corpus) ; clé de chaque fichier : ID Drive (google_drive_source.resource_ids[0].resource_id) ou URI GCS (gcs_source.uris[0]).
4. Supprimer du corpus tout fichier présent et non souhaité (supprimé, déplacé hors du dossier, dossier retiré).
5. Importer : pour Drive, seulement les fichiers nouveaux ou dont la date de modification Drive est postérieure à leur dernière indexation, par lots de 25 (https://drive.google.com/file/d/<ID>) ; pour les dépôts, le préfixe gs://BUCKET/uploads/. Vérifié : RAG Engine saute l'inchangé pour GCS, mais réimporte tout fichier Drive à chaque import (5 imports sur 5) — d'où ce filtre, sinon chaque passe re-parserait tout Drive.
6. Écrire un rapport sync/last.json (compteurs, erreurs, durée) lu par l'interface ; le détail par fichier va dans sync/runs/<horodatage>.ndjson (import_result_sink).

Concurrence : un seul import à la fois par corpus (sinon FailedPrecondition: There are other operations running, vérifié). → chaque action lance une nouvelle exécution du job ; une passe qui trouve le corpus occupé attend 15 s et recommence entièrement (listing frais), jusqu'à 15 min. La dernière passe lancée voit donc le dernier état.

Plafond connu : le listing Drive complet à chaque passe convient jusqu'à quelques milliers de fichiers. Au-delà : API changes de Drive (jeton de page stocké dans le bucket).

3.2 Qualité du RAG (réglages par défaut)

3.3 Interface (1 page)

• Sources : ajouter un dossier Drive (URL ou ID) ; l'interface vérifie qu'elle voit le dossier et affiche les 2 adresses à ajouter au partage ; retirer un dossier.
• Dépôt : glisser-déposer (ou parcourir), 30 Mo max par fichier (limite de requête Cloud Run 32 Mo).
• Documents : liste du corpus (nom, origine Drive/dépôt, date), suppression des fichiers déposés.
• Synchro : état de la dernière passe, bouton « Synchroniser maintenant ».
• Chat : réponses en streaming (/run_sse), citations cliquables, nouvelle conversation.

4. Identités et droits

Accès à l'interface : service privé ; on y accède par gcloud run services proxy rag-kit (marche avec un compte Gmail, sans organisation, vérifié). Option documentée : IAP sur Cloud Run (iap_enabled) quand le projet a une organisation.

Choix assumé : un seul compte de service pour le service et le job (ils touchent les mêmes ressources ; les rôles RAG Engine ne distinguent pas lecture et écriture). Séparation possible, décrite en 07.

5. Configuration (config/<nom>.env)

6. Livrables

01-rag-engine-sync/
├── README.md                  démarrage en 5 commandes
├── config/                    exemple.env, test.env (Terraform), test-shell.env (shell)
├── app/                       code (1 image : service + job), Dockerfile, requirements.txt
├── terraform/                 toute l'infra (corpus et palier RAG compris)
├── scripts/                   deployer_shell.sh, supprimer_shell.sh, ouvrir_interface.sh,
│                              test_e2e.py, config.sh  (le contrôle des partages Drive est fait
│                              par l'interface et par chaque passe de synchro)
├── tests/                     test_sync.py (logique de diff, sans réseau)
└── docs/
    00-spec.md                 (ce document)
    01-comprendre-et-choisir.md  marché + 3 approches
    02-prerequis.md            poste, comptes, API
    03-1-deployer-shell.md · 03-2-deployer-terraform.md · 03-3-deployer-console.md
    04-connecter-drive.md      partage, vérification, pièges
    05-utiliser-interface.md
    06-synchro-exploitation.md fréquence, logs, rapports, réindexation complète
    07-droits-iam.md           matrice détaillée, variantes
    08-couts.md
    09-depannage.md
    10-tout-supprimer.md

7. Validation (critères d'acceptation)

1. pytest : logique de diff (ajout, suppression, dossier retiré, fichier hors sources) — vert.
2. scripts/test_e2e.py <url du proxy> sur le projet déployé, chaque étape vérifiée par une assertion : dépôt d'un fichier contenant un fait unique → synchro → l'agent répond avec ce fait et cite le fichier → modification → nouvelle réponse → suppression → synchro → fichier absent du corpus.
3. Même scénario sur Drive (dossier de test partagé) : ajout dans un sous-dossier, suppression (corbeille).
4. Déploiement Terraform et shell : chacun déployé, testé (e2e), supprimé.
5. Chaque doc porte un bloc « Testé en vrai » daté avec les vraies sorties.

8. Faits vérifiés avant conception (14/10/2026, main-project-511608)

9. v2 — Connexion Google, « tout mon Drive » ou dossiers, synchro push

Demande (14/10/2026) : l'utilisateur connecte son Google Drive depuis l'interface, choisit tout son Drive ou des dossiers (sélecteur Google), active ou non la synchro automatique par source ; ajout, modification et suppression se propagent seuls, le plus vite possible. SharePoint et OneDrive affichés « bientôt ».

9.1 Pourquoi un miroir

« Tout mon Drive » ne peut pas être partagé avec l'agent de service RAG. Le kit lit donc Drive avec le compte de l'utilisateur (OAuth), recopie chaque fichier dans gs://BUCKET/mirror/<source>/<fileId>/<nom> (Docs → .docx, Slides → .pptx, Sheets et Dessins → .pdf, le reste tel quel si son type est indexable) avec en métadonnées le lien Drive et le titre, puis indexe ce préfixe. Avantages : RAG Engine saute l'inchangé côté GCS (vérifié), un seul mécanisme pour toutes les sources (OneDrive/SharePoint suivront par Microsoft Graph vers le même miroir), et les citations pointent vers le lien Drive d'origine.

La source « dossier partagé avec le kit » (v1, sans connexion) reste disponible.

9.2 Détection des changements (du plus rapide au filet de sécurité)

auto = false sur une source : ni canal ni passe planifiée pour elle ; seulement « Synchroniser maintenant ».

9.3 Identités et secrets

La connexion est au niveau du kit : un compte connecté sert à toutes les personnes qui ouvrent l'interface (comme le corpus). Redirection OAuth : http://localhost:8080/auth/google/callback (le proxy, port 8080).

9.4 Interface

Panneau Sources : carte Google Drive (bouton « Se connecter avec Google », puis « Tout mon Drive » ou « Choisir des dossiers » via le sélecteur Google, interrupteur « Synchro auto » par source, retrait) ; carte Dossier partagé avec le kit (v1) ; cartes OneDrive et SharePoint « bientôt ».

9.5 Validation

Tests automatiques avec un compte de service comme compte connecté (mêmes appels Drive : miroir, changes, changes.watch) : ajout, modification, suppression, déplacement hors dossier, notification push → indexé en moins d'une minute, désactivation de l'auto. La connexion OAuth réelle (écran Google) est validée par l'utilisateur.