> ## Documentation Index > Fetch the complete documentation index at: https://docs.lighton.ai/llms.txt > Use this file to discover all available pages before exploring further. # Uploader des fichiers vers Paradigm > Uploadez des documents vers Paradigm en utilisant l'API V3 Files - un processus simplifié en une seule étape avec prise en charge des uploads unitaires et par lot. ## Aperçu L'API V3 Files fournit un **processus d'upload simplifié en une seule étape** pour ajouter des documents à votre espace de travail Paradigm. Uploadez un fichier avec un seul appel API, et Paradigm s'occupe du reste - parsing, indexation et mise à disposition pour la recherche. **Fonctionnalités clés :** * **Traitement asynchrone** - Les fichiers sont mis en file d'attente et traités en arrière-plan, les uploads retournent donc immédiatement * **Sessions d'upload automatiques** - Les fichiers sont automatiquement regroupés en sessions pour un traitement par lot efficace * **Attribution directe de tags** - Organisez vos documents en leur attribuant des tags lors de l'upload * **Configuration flexible** - Surchargez la sélection du parser ou utilisez la détection automatique * **Suivi de progression** - Surveillez le statut du traitement via les endpoints GET ## Prérequis ### Requis * **Clé API Paradigm** : Générez-en une dans `/settings/api-key` de votre instance Paradigm * **ID d'espace de travail** : L'ID de l'espace de travail où les documents seront stockés ### Exigences sur les fichiers * **Taille maximale** : 100 Mo par fichier * **Formats supportés** : PDF, DOCX, DOC, TXT, MD, Markdown, HTML, XLSX, XLS, PPTX, PPT, CSV, RTF, ODT, ODS, ODP, EPUB, et plus ### Comment trouver l'ID de votre espace de travail Vous pouvez trouver l'ID de votre espace de travail de plusieurs façons : 1. **Depuis le panneau d'administration** : Naviguez vers votre espace de travail dans l'interface d'administration et vérifiez l'URL ou les détails de l'espace de travail 2. **Depuis l'API** : Listez vos espaces de travail avec `GET /api/v3/workspaces` ```bash theme={null} curl $PARADIGM_BASE_URL/api/v3/workspaces \ -H "Authorization: Bearer $PARADIGM_API_KEY" ``` ## Démarrage rapide L'upload le plus simple nécessite uniquement un fichier et un ID d'espace de travail : ### Python ```python theme={null} import requests import os # Récupérer la clé API et l'URL de base depuis l'environnement api_key = os.getenv("PARADIGM_API_KEY") base_url = os.getenv("PARADIGM_BASE_URL", "https://paradigm.lighton.ai") response = requests.post( f"{base_url}/api/v3/files", headers={"Authorization": f"Bearer {api_key}"}, files={"file": open("document.pdf", "rb")}, data={"workspace_id": 42} ) print(response.json()) ``` ### cURL ```bash theme={null} curl $PARADIGM_BASE_URL/api/v3/files \ -H "Authorization: Bearer $PARADIGM_API_KEY" \ -F "file=@document.pdf" \ -F "workspace_id=42" ``` ### Réponse ```json theme={null} { "id": 12345, "filename": "document.pdf", "workspace": {"id": 42, "name": "My Workspace", "workspace_type": "custom"}, "summaries": [], "title": "document", "extension": "pdf", "status": "pending", "status_vision": null, "created_at": "2025-03-01T10:30:00Z", "updated_at": "2025-03-01T10:30:00Z", "total_pages": 0, "tags": [], "created_by": {"id": 1, "first_name": "Jane", "last_name": "Doe", "username": "jdoe"}, "upload_session_uuid": "550e8400-e29b-41d4-a716-446655440000", "external_metadata": null, "message": "File queued for processing" } ``` ## Paramètres d'upload ### Paramètres requis | Paramètre | Type | Description | | -------------- | ------- | -------------------------------------------- | | `file` | binaire | Le fichier à uploader | | `workspace_id` | entier | Espace de travail où le document sera stocké | ### Paramètres optionnels | Paramètre | Type | Description | | ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | chaîne | Titre personnalisé pour le document (par défaut : le nom du fichier sans extension) | | `filename` | chaîne | Surcharger le nom du fichier uploadé | | `parser` | chaîne | Spécifier le pipeline d'ingestion (ex. "v2.2.1", "v2.1") - sélection automatique par défaut | | `tags` | tableau d'entiers | IDs de tags à attribuer au document lors de l'upload (les tags doivent appartenir à votre entreprise et vous devez avoir la permission de les utiliser) | ### Exemples avec paramètres optionnels **Titre personnalisé et tags :** ```python theme={null} response = requests.post( f"{base_url}/api/v3/files", headers={"Authorization": f"Bearer {api_key}"}, files={"file": open("Q4_report.pdf", "rb")}, data={ "workspace_id": 42, "title": "Rapport Financier Q4 2025", "tags": [1, 2] # IDs de tags } ) ``` **Parser personnalisé :** ```python theme={null} response = requests.post( f"{base_url}/api/v3/files", headers={"Authorization": f"Bearer {api_key}"}, files={"file": open("technical_doc.pdf", "rb")}, data={ "workspace_id": 42, "parser": "v2.2.1" } ) ``` ## Suivi du statut d'upload Après l'upload, les fichiers sont traités de manière asynchrone. Suivez leur progression à l'aide de l'ID du fichier. ### Vérifier le statut d'un fichier ```python theme={null} file_id = 12345 response = requests.get( f"{base_url}/api/v3/files/{file_id}", headers={"Authorization": f"Bearer {api_key}"} ) status = response.json()["status"] print(f"Statut du traitement : {status}") ``` ### Comprendre les valeurs de statut | Statut | Description | | ---------- | --------------------------------------------------------------------- | | `pending` | Fichier uploadé, en attente de traitement | | `parsing` | En cours de parsing et de traitement | | `embedded` | Traité avec succès et disponible pour la recherche | | `failed` | Échec du traitement (vérifiez le champ `status_detail` pour l'erreur) | ## Upload par lot : fichiers multiples Lors de l'upload de plusieurs fichiers, Paradigm crée automatiquement une **session d'upload** pour regrouper vos fichiers. Les fichiers sont mis en file d'attente et traités de manière asynchrone en arrière-plan, vous permettant d'uploader des lots importants sans attendre la fin du traitement. Chaque upload de fichier retourne un `upload_session_uuid` que vous pouvez utiliser pour suivre tous les fichiers du lot. La session d'upload gère la limitation de débit et assure un traitement efficace de vos documents. Pour uploader de nombreux fichiers efficacement, utilisez le script d'upload par lot fourni ou implémentez votre propre logique d'upload concurrent. ### Suivre tous les fichiers d'un upload par lot Après avoir uploadé plusieurs fichiers, vous pouvez filtrer par l'`upload_session_uuid` retourné dans chaque réponse d'upload : ```python theme={null} upload_session_uuid = "550e8400-e29b-41d4-a716-446655440000" response = requests.get( f"{base_url}/api/v3/files", headers={"Authorization": f"Bearer {api_key}"}, params={"upload_session_uuid": upload_session_uuid} ) files = response.json()["results"] for file in files: print(f"{file['filename']}: {file['status']}") ``` Ceci est particulièrement utile pour surveiller la progression des uploads par lot. ### Utilisation du script d'upload par lot Script de production pour l'upload asynchrone par lot avec uploads simultanés, suivi de progression et capacité de reprise. **Prérequis :** * Python 3.10 ou supérieur * [uv](https://docs.astral.sh/uv/) — les dépendances sont installées automatiquement lors de l'exécution avec `uv run` **Utilisation basique :** ```bash theme={null} uv run batch_upload_v3.py \ --api-key="votre_cle_api" \ --base-url="https://paradigm.lighton.ai" \ --files-dir="/chemin/vers/documents" \ --workspace-id=42 ``` **Avec options :** ```bash theme={null} uv run batch_upload_v3.py \ --files-dir="/chemin/vers/documents" \ --workspace-id=42 \ --batch-size=20 \ --max-fails=5 \ --tags=1,2,3 \ --state-file="upload_state.json" ``` **Uploader uniquement certains types de fichiers :** ```bash theme={null} # Uploader uniquement les PDF et documents Word uv run batch_upload_v3.py \ --files-dir="/chemin/vers/documents" \ --workspace-id=42 \ --include-extensions=pdf,docx,doc # Uploader tous les fichiers sauf les fichiers temporaires et système uv run batch_upload_v3.py \ --files-dir="/chemin/vers/documents" \ --workspace-id=42 \ --exclude-extensions=tmp,log,.DS_Store,.gitkeep ``` ### Arguments du script | Argument | Description | Valeur par défaut | | ---------------------- | --------------------------------------------------------------------------------------------- | ----------------------------- | | `--api-key` | Clé API Paradigm (ou définir la variable d'environnement `PARADIGM_API_KEY`) | Requis | | `--base-url` | URL de l'instance Paradigm (ou définir la variable d'environnement `PARADIGM_BASE_URL`) | `https://paradigm.lighton.ai` | | `--files-dir` | Répertoire contenant les fichiers à uploader (scan récursif) | Requis | | `--workspace-id` | ID de l'espace de travail où les fichiers seront stockés | Requis | | `--batch-size` | Nombre d'uploads simultanés (max : 50) | `10` | | `--max-fails` | Arrêter après N échecs (doit être >= 1) | `1` | | `--tags` | IDs de tags séparés par des virgules à appliquer à tous les fichiers | Aucun | | `--state-file` | Fichier JSON pour suivre la progression et permettre la reprise | Aucun | | `--include-extensions` | Uploader uniquement les fichiers avec ces extensions ou noms de fichiers (ex. `pdf,docx,txt`) | Aucun (tous les fichiers) | | `--exclude-extensions` | Ignorer les fichiers avec ces extensions ou noms de fichiers (ex. `tmp,log,.DS_Store`) | Aucun | ### Fonctionnalités du script * **Haut débit** - uploads simultanés optimisés pour la vitesse (par défaut : 10 simultanés, max : 50) * **Scan récursif** - trouve automatiquement tous les fichiers dans les sous-répertoires * **Suivi de progression** - barre de progression en temps réel avec statistiques d'upload * **Résilience aux erreurs** - s'arrête après le premier échec par défaut (configurable avec `--max-fails`) * **Gestion intelligente des erreurs** - ignore automatiquement les fichiers avec des extensions non supportées et les fichiers > 100 Mo (non comptés comme échecs) * **Capacité de reprise** - utilisez `--state-file` pour reprendre les uploads interrompus * **Tagging en masse** - appliquer des tags à tous les fichiers uploadés automatiquement ### Exemple : reprendre après une interruption Si votre upload a été interrompu, reprenez en utilisant le fichier d'état : ```bash theme={null} # Première tentative (interrompue) uv run batch_upload_v3.py \ --files-dir="/chemin/vers/documents" \ --workspace-id=42 \ --state-file="upload_state.json" # Reprise (ignore les fichiers déjà uploadés) uv run batch_upload_v3.py \ --files-dir="/chemin/vers/documents" \ --workspace-id=42 \ --state-file="upload_state.json" ``` ## Migration depuis la V2 Si vous utilisez actuellement l'API d'upload V2, voici ce qui a changé : ### Ce qui a changé **La V2 nécessitait deux étapes :** 1. Créer une session d'upload : `POST /api/v2/upload-session` 2. Uploader les fichiers vers la session : `POST /api/v2/upload-session/{uuid}` **La V3 se fait en une seule étape :** * Uploadez directement : `POST /api/v3/files` ### Ce qui a été supprimé Les concepts suivants de la V2 ne sont plus nécessaires : * **Gestion des sessions d'upload** - Les sessions sont créées automatiquement en arrière-plan * **Types de collection** - Utilisez simplement `workspace_id` au lieu de `collection_type` et `collection` * **Configuration OCR** - Les paramètres de traitement sont appliqués automatiquement (ou surchargez avec le paramètre `parser`) * **Activation/désactivation de session** - Gérée automatiquement * **Champ `purpose`** - Plus nécessaire ### Nouveautés La V3 ajoute de nouvelles fonctionnalités non disponibles en V2 : * **Attribution directe de tags** - Utilisez le paramètre `tags` pour tagger les documents lors de l'upload * **Suivi de statut simplifié** - Filtrez les fichiers par `upload_session_uuid` pour suivre les uploads par lot ### Suivi de la progression **V2 :** Suivre le statut de la session avec `GET /api/v2/upload-session/{uuid}` **V3 :** Filtrer les fichiers par UUID de session d'upload : ```python theme={null} # Récupérer l'UUID de la session d'upload depuis la réponse upload_session_uuid = response.json()["upload_session_uuid"] # Suivre tous les fichiers de ce lot files = requests.get( f"{base_url}/api/v3/files", headers={"Authorization": f"Bearer {api_key}"}, params={"upload_session_uuid": upload_session_uuid} ).json()["results"] ``` L'API V3 est plus intuitive et nécessite moins de code tout en maintenant la même fiabilité et performance que la V2.