Premiers pas

Bienvenue dans NIA One. Ce guide vous mène de zéro à une intégration totalement saine, en Python comme en TypeScript. Utilisez le sélecteur de langage en haut de page : tous les exemples basculent d'un coup.

Le parcours

1. 1

   Créer un SIA

   Un SIA (Service IA) représente une application IA que vous instrumentez. Depuis le cockpit, ouvrez SIA → Nouveau (/sia/new) et choisissez son type (conversationnel, agent, pipeline…).

2. 2

   Générer une clé API

   Ouvrez votre SIA → onglet Settings → API Keys → Générer. La clé n'est affichée qu'une seule fois : copiez-la immédiatement. Vous pouvez la régénérer ou la révoquer à tout moment.

3. 3

   Installer le SDK

   Les SDK s'installent depuis le registre NIA One (npm @niaone/sdk, PyPI niaone-python-sdk) : juste une URL, aucun token. L'URL exacte de votre instance s'affiche sur la page SDK (menu latéral, au-dessus de « Docs ») et dans l'assistant de création de SIA.

   PythonTypeScript

   # Aucun token — juste l'extra-index-url (remplacez <votre-domaine> par votre instance)pip install niaone-python-sdk \--extra-index-url https://registry.<votre-domaine>/pypi/simple/

   Où trouver votre URL

   La page SDK (menu latéral, au-dessus de « Docs ») affiche les commandes exactes pour votre instance, prêtes à copier. Le registre masque l'origine GitLab : la source n'est jamais exposée.

4. 4

   Configurer les variables d'environnement

   Le client lit ces variables si vous ne passez rien explicitement.

   .env

   NIAONE_API_KEY=sk_votre_cleNIAONE_BASE_URL=https://api.niaone.example# optionnelNIAONE_TENANT_ID=NIAONE_DISABLED=        # 1 => SDK no-op (utile en local/CI)NIAONE_SAFE_MODE=       # 1 => erreurs routées vers on_error au lieu de lever

Premier flow instrumenté

Tout span (mesure d'une opération) s'inscrit dans un flow, c'est-à-dire un parcours complet : une conversation, une requête, un job. Un flow contient des étapes (steps) ; chaque étape émet des enregistrements (records) : entrées/sorties, métriques…

from niaone_sdk import NiaoneSDK, start_flow, end_flow, start_step, end_step, payloadfrom niaone_sdk.models import Asset, Flow, Datafrom niaone_sdk.enums import AssetKind, AssetRole, FlowPhase, DataRole, DataKind, DataFormatclient = NiaoneSDK(api_key="sk_...", base_url="https://api.niaone.example")flow = start_flow(client, flow_definition_id="support_bot", name="support_bot_main")try:  step = start_step(      flow,      asset=Asset(kind=AssetKind.LLM, role=AssetRole.ANALYSIS, name="gpt-4o", provider="openai"),      flow=Flow(name="support_bot_main", phase=FlowPhase.ANALYSIS, step="answer"),  )  # ... votre logique métier ...  payload(step, "output",          Data(role=DataRole.OUTPUT, kind=DataKind.COMPLETION, format=DataFormat.TEXT),          "Bonjour ! Voici comment réinitialiser votre mot de passe…")  end_step(step, "success", metrics={"input_tokens": 45, "output_tokens": 120})finally:  end_flow(flow, "success")  client.close()  # flush des events restants

Encore plus simple : une ligne par framework

Si votre SIA est une API web, un middleware (composant qui s'intercale dans le traitement des requêtes) instrumente tout le trafic HTTP sans écrire le moindre start_flow : chaque requête devient un flow (méthode, route, statut, latence, erreurs), et vos handlers gardent accès au flow via current_flow_from_context().

from flask import Flaskfrom niaone_sdk.integrations.flask import NiaoneFlaskapp = Flask(__name__)NiaoneFlask(app)   # c'est tout

Vérifier l'arrivée des données

Après exécution, attendez ~30 s (latence d'ingestion) puis, dans le cockpit /sia/<votre-sia> :

1. Onglet Explore → au moins une trace listée.
2. Onglet Quality → le score d'intégration (EXCELLENT au début, c'est normal sous 20 spans).

Si rien n'apparaît, voyez Troubleshooting (clé API, base_url, réseau).