Référence de la CLI du serveur

Paquet : piighost-api

piighost-api est la ligne de commande du serveur compagnon. serve démarre le serveur HTTP. Les commandes dataset construisent et notent un jeu de détections à partir des traces d'observation.

piighost-api serve [--config SOURCE] [--host HOST] [--port PORT] [--log-level LEVEL]
piighost-api dataset extract --output FILE [--since DATE] [--until DATE] [--mode MODE] [--limit N]
piighost-api dataset metrics --input FILE [--output FILE] [--output-format FORMAT] [--match-mode MODE] [--iou-threshold FLOAT] [--source SOURCE]

Le serveur demande Python 3.12 ou plus récent et piighost>=2.0,<3. Ses extras ajoutent des fonctions optionnelles :

pip install "piighost-api[gliner2,observation]"

piighost-api serve

Construit le pipeline une fois et sert les endpoints de l'API avec uvicorn, dans un seul processus.

piighost-api serve --config catalog:piighost/support-en --host 0.0.0.0 --port 8000

• Sans --config ni PIIGHOST_CONFIG, la commande imprime Missing --config or PIIGHOST_CONFIG. avec une indication d'usage et sort en 1. Un chemin de fichier qui n'existe pas sort en 1 avec Configuration file not found:.
• Une référence du catalogue charge la configuration complète que le catalogue piighost publie sous ce nom. Une référence épinglée à un commit est récupérée au premier démarrage, puis lue dans le cache disque.
• Une configuration qui ne déclare pas de section [memory] est servie avec la mémoire in-process, in_memory. Ses conversations vivent dans le processus du serveur, donc chaque instance tient les siennes. Plusieurs instances derrière un load balancer demandent une mémoire redis ou sqlalchemy partagée, voir Déploiement multi-instance.
• Toute section de premier niveau se surcharge avec une variable PIIGHOST_ qui porte un objet JSON, comme pour un fichier, voir Surcharges d'environnement. PIIGHOST_MEMORY ajoute ainsi une mémoire partagée à une configuration du catalogue. Celle de l'exemple ci-dessous demande piighost[crypto] pour son cipher.
• Sans clé dans une variable API_KEY_, le serveur refuse de démarrer sauf si PIIGHOST_ALLOW_ANONYMOUS est posée.

export PIIGHOST_MEMORY='{"type": "redis", "url": "redis://redis:6379/0", "hasher": {"type": "argon2"}, "cipher": {"type": "aesgcm"}}'
piighost-api serve --config catalog:piighost/support-en

Variables d'environnement

Le pipeline lit ses propres secrets (PIIGHOST_HASH_PEPPER, PIIGHOST_CIPHER_KEY, PIIGHOST_DATABASE_URL et MISTRAL_API_KEY). PIIGHOST_CATALOG_URL nomme un catalogue privé. Ces variables sont listées dans la Référence TOML. Les autres variables OTEL_*, en-têtes compris, sont lues par l'exporteur OpenTelemetry lui-même, voir Observation.

L'image Docker en lit quatre de plus, listées dans Déployer un pipeline en production.

piighost-api dataset extract

Lit des traces sur Langfuse et écrit un enregistrement JSONL par trace. Il demande l'extra dataset ainsi que LANGFUSE_PUBLIC_KEY et LANGFUSE_SECRET_KEY, lues dans l'environnement ou dans un fichier .env du répertoire courant. Sans elles, il sort en 1.

piighost-api dataset extract --output dataset.jsonl --since 2026-09-01 --limit 1000

Une trace sans texte d'entrée, ou une trace de modèle sans son enfant piighost.detect, est ignorée. La commande se termine par Wrote N records to FILE (M skipped).

{
  "text": "Hi Jane Doe, from Acme in Boston",
  "entities": [[3, 11, "PERSON"], [18, 22, "ORGANIZATION"], [26, 32, "LOCATION"]],
  "model_entities": [[3, 11, "PERSON"], [18, 22, "LOCATION"]],
  "labels_universe": [],
  "source": "hitl",
  "trace_id": "...",
  "session_id": "...",
  "created_at": "..."
}

piighost-api dataset metrics

Note le modèle contre la référence d'un fichier JSONL écrit par dataset extract, label par label. Il ne demande aucun extra.

piighost-api dataset metrics --input dataset.jsonl

Sur l'enregistrement ci-dessus, le tableau est :

label                    tp     fp     fn      P      R     F1
--------------------------------------------------------------
LOCATION                  0      1      1   0.00   0.00   0.00
ORGANIZATION              0      0      1   0.00   0.00   0.00
PERSON                    1      0      0   1.00   1.00   1.00
--------------------------------------------------------------
macro avg                 -      -      -   0.33   0.33   0.33
micro avg                 -      -      -   0.50   0.33   0.40

Label confusion (model -> human, same span):
  LOCATION -> ORGANIZATION: 1

tp compte un span du modèle que la référence contient, fp un span du modèle qu'elle ne contient pas, fn un span de référence que le modèle a manqué. P, R et F1 sont la précision, le rappel et leur moyenne harmonique. La section de confusion liste les spans où le modèle et la référence s'accordent sur les décalages et diffèrent sur le label.

Voir aussi

• Endpoints de l'API : chaque route que le serveur sert.
• Déployer une API de dé-identification : un premier serveur, pas à pas.
• CLI : la commande piighost de la librairie.