Uploader des fichiers vers Paradigm

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 :

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
Depuis l’API : Listez vos espaces de travail avec GET /api/v3/workspaces

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

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

curl $PARADIGM_BASE_URL/api/v3/files \
  -H "Authorization: Bearer $PARADIGM_API_KEY" \
  -F "file=@document.pdf" \
  -F "workspace_id=42"

Réponse

{
  "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 :

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é :

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

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 :

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

batch_upload_v3.py

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 — les dépendances sont installées automatiquement lors de l’exécution avec uv run

Utilisation basique :

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 :

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 :

# 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 :

# 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 :

Créer une session d’upload : POST /api/v2/upload-session
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 :

# 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.

Fondamentaux API

Modèles LightOn

Agents et Threads

Chat et Modèles IA

Gestion des Documents

Aperçu

Prérequis

Requis

Exigences sur les fichiers

Comment trouver l’ID de votre espace de travail

Démarrage rapide

Python

cURL

Réponse

Paramètres d’upload

Paramètres requis

Paramètres optionnels

Exemples avec paramètres optionnels

Suivi du statut d’upload

Vérifier le statut d’un fichier

Comprendre les valeurs de statut

Upload par lot : fichiers multiples

Suivre tous les fichiers d’un upload par lot

Utilisation du script d’upload par lot

batch_upload_v3.py

Arguments du script

Fonctionnalités du script

Exemple : reprendre après une interruption

Migration depuis la V2

Ce qui a changé

Ce qui a été supprimé

Nouveautés

Suivi de la progression

​Aperçu

​Prérequis

​Requis

​Exigences sur les fichiers

​Comment trouver l’ID de votre espace de travail

​Démarrage rapide

​Python

​cURL

​Réponse

​Paramètres d’upload

​Paramètres requis

​Paramètres optionnels

​Exemples avec paramètres optionnels

​Suivi du statut d’upload

​Vérifier le statut d’un fichier

​Comprendre les valeurs de statut

​Upload par lot : fichiers multiples

​Suivre tous les fichiers d’un upload par lot

​Utilisation du script d’upload par lot

batch_upload_v3.py

​Arguments du script

​Fonctionnalités du script

​Exemple : reprendre après une interruption

​Migration depuis la V2

​Ce qui a changé

​Ce qui a été supprimé

​Nouveautés

​Suivi de la progression

Aperçu

Prérequis

Requis

Exigences sur les fichiers

Comment trouver l’ID de votre espace de travail

Démarrage rapide

Python

cURL

Réponse

Paramètres d’upload

Paramètres requis

Paramètres optionnels

Exemples avec paramètres optionnels

Suivi du statut d’upload

Vérifier le statut d’un fichier

Comprendre les valeurs de statut

Upload par lot : fichiers multiples

Suivre tous les fichiers d’un upload par lot

Utilisation du script d’upload par lot

Arguments du script

Fonctionnalités du script

Exemple : reprendre après une interruption

Migration depuis la V2

Ce qui a changé

Ce qui a été supprimé

Nouveautés

Suivi de la progression