Gestion et modélisation automatiques de l'ontologie

Objectif

Inspecter et modifier la couche sémantique d'Auto Ontology sans confondre un appel API réussi avec une signification métier correcte ou une publication durable. Les entrées, sorties, statuts, gates et handoffs lisibles par machine se trouvent dans runtime-contract.yaml.

Choisissez le workflow ciblé avant d'agir :

inspection de routine ou éditions de métadonnées : continuez ci-dessous et utilisez write-api.md ;
concepts, relations, mesures, unités, grain ou politiques : utilisez modeling.md ;
promotion de modèle ou résultats analytiques réutilisables : utilisez publication.md.

Les outils MCP lisent uniquement. Create, patch, import et compile-reset passent par la passerelle Next.js /api/.... Les lignes de résultats régies nécessitent un writer source approuvé ; Auto Ontology n'a pas de point de terminaison générique de writeback de ligne de résultats. Les corps de requête et les types de champs se trouvent dans docs/openapi/auto-ontology-api.json ; cette skill nomme uniquement les opérations et permissions.

Prérequis

Utilisez un déploiement Auto Ontology en cours d'exécution et authentifié. Utilisez nvidia-ontology-setup lorsque le déploiement ou la couche sémantique ne sont pas prêts.

Limitations

MCP est en lecture seule, Auto Ontology n'a pas de point de terminaison générique de writeback de ligne de résultats, et les API actuelles d'import et certification de modèles ne prouvent pas la promotion atomique. Suivez les gates de publication ci-dessous et échouez fermé quand la relecture exacte est indisponible.

Authentification

Les scripts utilisent un token API (x-api-key ou Authorization: Bearer). Générez-le dans l'interface utilisateur (menu utilisateur → API Tokens). Un token agit comme son propriétaire — le token d'un lecteur ne peut pas faire des choses d'admin. La création et la révocation de tokens nécessitent une session connectée ; un token ne peut pas générer un autre token.

Les écritures ci-dessous nécessitent catalog:edit sauf indication contraire. 403 signifie que le rôle du propriétaire manque cette permission, pas que le chemin est incorrect.

Instructions

Découvrez la signification actuelle via MCP (search_terms, get_term, get_term_columns, get_term_sql_attributes, describe_table) ou REST si MCP est absent (GET /api/terms, GET /api/terms/{term_id}, GET /api/exploration/tables/{table_id}/details).
Résolvez le contrat sémantique quand la signification change. Enregistrez la liaison source, l'identité, la population, la cardinalité de la relation, l'expression de mesure, l'unité, le grain, le dénominateur, le temps, la validité et les contre-exemples ; voir modeling.md.
Énoncez le changement proposé à l'utilisateur (renommage de terme, nouvel attribut SQL, import, etc.). Ne réécrivez pas silencieusement le glossaire.
Validez le SQL avant create/update : POST /api/sql-attributes/validate. Un échec d'analyse est HTTP 422, pas valid: false.
Appliquez la plus petite écriture qui correspond à la demande (voir write-api.md).
La compilation n'est pas un effet secondaire caché. Vérifiez GET /api/semantic-compilation/status. N'appelez pas POST /api/semantic-compilation/reset comme nettoyage — c'est une reconstruction asynchrone et destructrice de la couche compilée de chaque base de données, retourne 202, et nécessite semanticCompilation:manage.
Vérifiez le changement persisté, pas seulement le succès de la demande. Les imports de modèle nécessitent une sauvegarde ciblée et une comparaison de ré-export exacte ; voir publication.md. Puis utilisez MCP check_answerable / ask_question (ou REST POST /api/question-entity-coverage et POST /api/chat/completions) pour les vérifications de comportement positives et négatives.

Relations sémantiques et « qu'est-ce que cet ensemble de données signifie »

Restez sur la couche sémantique. Ne parcourez pas les schémas bruts pour répondre à la signification.

Term → colonnes : MCP get_term_columns ou GET /api/terms/{term_id}/column-attributes
Term → SQL dérivé : MCP get_term_sql_attributes
Table → terms et attributs SQL : MCP describe_table ou GET /api/exploration/tables/{table_id}/details
Chaîne de saut sémantique entre deux terms : GET /api/exploration/terms/{term_id}/path/{other_term_id}
Graphiques sémantiques : GET /api/exploration/graph, GET /api/exploration/semantic-graph

Ce sont des chemins de relations sémantiques, pas de la provenance de génération, révision source, historique de certification ou lignée de version.

Import / export en masse

POST /api/model/export — YAML du catalogue + couche sémantique. Permission modelInterchange:export. Le corps peut définir les IDs de base de données de catalogue dans databases (vide = tous) et format (auto_ontology ou ossie).
POST /api/model/import — YAML multipart ; Auto Ontology natif (data_layer / semantic_layer) ou Apache Ossie (version, name, datasets à la racine). Requête replace (par défaut true) et embed (par défaut true). Permission modelInterchange:import. Peut remplacer les données existantes — confirmez auprès de l'utilisateur avant replace=true, appliquez d'abord en isolation, et utilisez le workflow de relecture exacte dans publication.md.

Exemples

Pour définir une mesure au grain d'exécution, suivez le workflow de preuve et contre-exemple dans modeling.md.
Pour réviser et promouvoir un modèle, sauvegardez la portée exacte et suivez le workflow de relecture par étapes dans publication.md.

Dépannage

Pour les échecs d'écriture, vérifiez la permission du propriétaire authentifié, distinguez les échecs d'analyse HTTP 422 des résultats de validation, et inspectez l'état de compilation avant de modifier le modèle ou de réinitialiser la compilation.

Voir aussi

write-api.md
modeling.md
publication.md
nvidia-ontology-query — comment appeler Auto Ontology et valider les résultats de requête
nvidia-ontology-setup — déploiement non prêt
mcp/auto_ontology_mcp/tools.py — liste d'autorisation des outils de lecture en direct

nvidia-ontology-management