Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Interrogation d’entités de lignée
<a name="querying-lineage-entities"></a>

Amazon SageMaker AI génère automatiquement des graphiques des entités de lignée lorsque vous les utilisez. Vous pouvez interroger ces données pour répondre à diverses questions. Vous trouverez ci-dessous des instructions sur la manière d’interroger ces données dans le kit SDK pour Python. 

Pour plus d'informations sur la façon de consulter une lignée de modèles enregistrés dans Amazon SageMaker Studio, consultez[Visualisation des détails de traçabilité de modèle dans Studio](model-registry-lineage-view-studio.md).

Vous pouvez interroger vos entités de lignée pour :
+ Récupérer tous les jeux de données impliqués dans la création d’un modèle.
+ Récupérer toutes les tâches impliquées dans la création d'un point de terminaison.
+ Récupérer tous les modèles utilisant un jeu de données.
+ Récupérer tous les points de terminaison qui utilisent un modèle.
+ Récupérer les points de terminaison qui proviennent d'un jeu de données précis.
+ Récupérer l'exécution du pipeline qui a créé une tâche d'entraînement.
+ Récupérer les relations entre les entités à des fins d’enquête, de gouvernance et de reproductibilité.
+ Récupérer tous les essais en aval qui utilisent l'artefact.
+ Récupérer tous les essais en amont qui utilisent l'artefact.
+ Récupérer la liste des artefacts qui utilisent l'URI S3 fourni.
+ Récupérer les artefacts en amont qui utilisent l'artefact de jeu de données.
+ Récupérer les artefacts en aval qui utilisent l'artefact de jeu de données.
+ Récupérer les jeux de données qui utilisent l'artefact d'image.
+ Récupérer les actions qui utilisent le contexte.
+ Récupérer les tâches de traitement qui utilisent le point de terminaison.
+ Récupérer les tâches de transformation qui utilisent le point de terminaison.
+ Récupérer les composants d'essai qui utilisent le point de terminaison.
+ Récupérer l'ARN pour l'exécution de pipeline associée au groupe de packages de modèles.
+ Récupérer tous les artefacts qui utilisent l'action.
+ Récupérer tous les jeux de données en amont qui utilisent l'action d'approbation de package de modèles.
+ Récupérer le package de modèles à partir de l'action d'approbation de package de modèles
+ Récupérer les contextes de point de terminaison en aval qui utilisent le point de terminaison.
+ Récupérer l'ARN pour l'exécution de pipeline associée au composant d'essai.
+ Récupérer les jeux de données qui utilisent le composant d'essai.
+ Récupérer les modèles qui utilisent le composant d'essai.
+ Explorer votre lignée à des fins de visualisation.

**Limitations**
+ L’interrogation de lignée n’est pas disponible dans les régions suivantes :
  + Afrique (Le Cap) – af-south
  + Asie-Pacifique (Jakarta) : ap-southeast-3
  + Asie-Pacifique (Osaka) – ap-northeast-3
  + Europe (Milan) – eu-south-1
  + Europe (Espagne) : eu-south-2
  + Israël (Tel Aviv) – il-central-1
+ La profondeur maximale des relations à découvrir est actuellement limitée à 10.
+ Le filtrage se limite aux propriétés suivantes : date de dernière modification, date de création, type et type d'entité de lignée. 

**Topics**
+ [Démarrer avec l'interrogation des entités de lignage](#querying-lineage-entities-getting-started)

## Démarrer avec l'interrogation des entités de lignage
<a name="querying-lineage-entities-getting-started"></a>

Il existe deux méthodes simples pour démarrer :
+ [Amazon SageMaker AI SDK pour Python](https://github.com/aws/sagemaker-python-sdk/blob/master/src/sagemaker/lineage/artifact.py#L397) qui a défini de nombreux cas d'utilisation courants.
+ [Pour un bloc-notes expliquant comment utiliser SageMaker AI Lineage APIs pour interroger les relations sur le graphe de lignage, voir sagemaker-lineage-multihop-queries .ipynb.](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-lineage/sagemaker-lineage-multihop-queries.ipynb)

Les exemples suivants montrent comment utiliser le `LineageQuery` et pour créer des requêtes `LineageFilter` APIs afin de répondre à des questions sur le graphe de lignage et d'extraire des relations entre entités pour quelques cas d'utilisation.

**Example Utilisation de l'API `LineageQuery` pour trouver des associations d'entités**  

```
from sagemaker.lineage.context import Context, EndpointContext
from sagemaker.lineage.action import Action
from sagemaker.lineage.association import Association
from sagemaker.lineage.artifact import Artifact, ModelArtifact, DatasetArtifact

from sagemaker.lineage.query import (
    LineageQuery,
    LineageFilter,
    LineageSourceEnum,
    LineageEntityEnum,
    LineageQueryDirectionEnum,
)
# Find the endpoint context and model artifact that should be used for the lineage queries.

contexts = Context.list(source_uri=endpoint_arn)
context_name = list(contexts)[0].context_name
endpoint_context = EndpointContext.load(context_name=context_name)
```

**Example Rechercher tous les jeux de données associés à un point de terminaison**  

```
# Define the LineageFilter to look for entities of type `ARTIFACT` and the source of type `DATASET`.

query_filter = LineageFilter(
    entities=[LineageEntityEnum.ARTIFACT], sources=[LineageSourceEnum.DATASET]
)

# Providing this `LineageFilter` to the `LineageQuery` constructs a query that traverses through the given context `endpoint_context`
# and find all datasets.

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[endpoint_context.context_arn],
    query_filter=query_filter,
    direction=LineageQueryDirectionEnum.ASCENDANTS,
    include_edges=False,
)

# Parse through the query results to get the lineage objects corresponding to the datasets
dataset_artifacts = []
for vertex in query_result.vertices:
    dataset_artifacts.append(vertex.to_lineage_object().source.source_uri)

pp.pprint(dataset_artifacts)
```

**Example Rechercher les modèles associés à un point de terminaison**  

```
# Define the LineageFilter to look for entities of type `ARTIFACT` and the source of type `MODEL`.

query_filter = LineageFilter(
    entities=[LineageEntityEnum.ARTIFACT], sources=[LineageSourceEnum.MODEL]
)

# Providing this `LineageFilter` to the `LineageQuery` constructs a query that traverses through the given context `endpoint_context`
# and find all datasets.

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[endpoint_context.context_arn],
    query_filter=query_filter,
    direction=LineageQueryDirectionEnum.ASCENDANTS,
    include_edges=False,
)

# Parse through the query results to get the lineage objects corresponding to the model
model_artifacts = []
for vertex in query_result.vertices:
    model_artifacts.append(vertex.to_lineage_object().source.source_uri)

# The results of the `LineageQuery` API call return the ARN of the model deployed to the endpoint along with
# the S3 URI to the model.tar.gz file associated with the model
pp.pprint(model_artifacts)
```

**Example Rechercher les composants d'évaluation associés au point de terminaison**  

```
# Define the LineageFilter to look for entities of type `TRIAL_COMPONENT` and the source of type `TRAINING_JOB`.

query_filter = LineageFilter(
    entities=[LineageEntityEnum.TRIAL_COMPONENT],
    sources=[LineageSourceEnum.TRAINING_JOB],
)

# Providing this `LineageFilter` to the `LineageQuery` constructs a query that traverses through the given context `endpoint_context`
# and find all datasets.

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[endpoint_context.context_arn],
    query_filter=query_filter,
    direction=LineageQueryDirectionEnum.ASCENDANTS,
    include_edges=False,
)

# Parse through the query results to get the ARNs of the training jobs associated with this Endpoint
trial_components = []
for vertex in query_result.vertices:
    trial_components.append(vertex.arn)

pp.pprint(trial_components)
```

**Example Changer le point focal de la lignée**  
La `LineageQuery` peut être modifiée pour avoir différents `start_arns` qui modifient le point focal de la lignée. En outre, le `LineageFilter` peut prendre plusieurs sources et entités pour étendre la portée de la requête.  
Dans l'exemple suivant, nous utilisons le modèle comme point focal de la lignée et nous recherchons les points de terminaison et les jeux de données qui lui sont associés.  

```
# Get the ModelArtifact

model_artifact_summary = list(Artifact.list(source_uri=model_package_arn))[0]
model_artifact = ModelArtifact.load(artifact_arn=model_artifact_summary.artifact_arn)
query_filter = LineageFilter(
    entities=[LineageEntityEnum.ARTIFACT],
    sources=[LineageSourceEnum.ENDPOINT, LineageSourceEnum.DATASET],
)

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[model_artifact.artifact_arn],  # Model is the starting artifact
    query_filter=query_filter,
    # Find all the entities that descend from the model, i.e. the endpoint
    direction=LineageQueryDirectionEnum.DESCENDANTS,
    include_edges=False,
)

associations = []
for vertex in query_result.vertices:
    associations.append(vertex.to_lineage_object().source.source_uri)

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[model_artifact.artifact_arn],  # Model is the starting artifact
    query_filter=query_filter,
    # Find all the entities that ascend from the model, i.e. the datasets
    direction=LineageQueryDirectionEnum.ASCENDANTS,
    include_edges=False,
)

for vertex in query_result.vertices:
    associations.append(vertex.to_lineage_object().source.source_uri)

pp.pprint(associations)
```

**Example Utilisation de `LineageQueryDirectionEnum.BOTH` pour rechercher des relations ascendantes et descendantes**  
Lorsque la direction est définie sur `BOTH`, la requête parcourt le graphique pour trouver les relations ascendantes et descendantes. Cette traversée s'effectue non seulement à partir du nœud de départ, mais aussi de chaque nœud visité. Par exemple, si une tâche d'entraînement est exécutée deux fois et que les deux modèles générés par la tâche d'entraînement sont déployés sur des points de terminaison, le résultat de la requête avec la direction définie sur `BOTH` affiche les deux points de terminaison. En effet, la même image est utilisée pour l'entraînement et le déploiement du modèle. Étant donné que l'image est commune au modèle, le `start_arn` et les deux points de terminaison apparaissent dans le résultat de la requête.  

```
query_filter = LineageFilter(
    entities=[LineageEntityEnum.ARTIFACT],
    sources=[LineageSourceEnum.ENDPOINT, LineageSourceEnum.DATASET],
)

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[model_artifact.artifact_arn],  # Model is the starting artifact
    query_filter=query_filter,
    # This specifies that the query should look for associations both ascending and descending for the start
    direction=LineageQueryDirectionEnum.BOTH,
    include_edges=False,
)

associations = []
for vertex in query_result.vertices:
    associations.append(vertex.to_lineage_object().source.source_uri)

pp.pprint(associations)
```

**Example Directions dans `LineageQuery` - `ASCENDANTS` versus `DESCENDANTS`**  
Pour comprendre la direction dans le graphique de lignée, prenez le graphique de relations d'entité suivant - Jeu de données -> Tâche d'entraînement -> Modèle -> Point de terminaison  
Le point de terminaison est un descendant du modèle, et le modèle est un descendant du jeu de données. De même, le modèle est un ascendant du point de terminaison. Le paramètre `direction` peut être utilisé pour spécifier si la requête doit renvoyer des entités descendantes ou ascendantes de l'entité dans `start_arns`. Si le `start_arns` contient un modèle et que la direction est `DESCENDANTS`, la requête renvoie le point de terminaison. Si la direction est `ASCENDANTS`, la requête renvoie le jeu de données.  

```
# In this example, we'll look at the impact of specifying the direction as ASCENDANT or DESCENDANT in a `LineageQuery`.

query_filter = LineageFilter(
    entities=[LineageEntityEnum.ARTIFACT],
    sources=[
        LineageSourceEnum.ENDPOINT,
        LineageSourceEnum.MODEL,
        LineageSourceEnum.DATASET,
        LineageSourceEnum.TRAINING_JOB,
    ],
)

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[model_artifact.artifact_arn],
    query_filter=query_filter,
    direction=LineageQueryDirectionEnum.ASCENDANTS,
    include_edges=False,
)

ascendant_artifacts = []

# The lineage entity returned for the Training Job is a TrialComponent which can't be converted to a
# lineage object using the method `to_lineage_object()` so we extract the TrialComponent ARN.
for vertex in query_result.vertices:
    try:
        ascendant_artifacts.append(vertex.to_lineage_object().source.source_uri)
    except:
        ascendant_artifacts.append(vertex.arn)

print("Ascendant artifacts : ")
pp.pprint(ascendant_artifacts)

query_result = LineageQuery(sagemaker_session).query(
    start_arns=[model_artifact.artifact_arn],
    query_filter=query_filter,
    direction=LineageQueryDirectionEnum.DESCENDANTS,
    include_edges=False,
)

descendant_artifacts = []
for vertex in query_result.vertices:
    try:
        descendant_artifacts.append(vertex.to_lineage_object().source.source_uri)
    except:
        # Handling TrialComponents.
        descendant_artifacts.append(vertex.arn)

print("Descendant artifacts : ")
pp.pprint(descendant_artifacts)
```

**Example Fonctions d'assistance de kit SDK pour faciliter les requêtes de lignée**  
Les classes `EndpointContext`, `ModelArtifact` et `DatasetArtifact` ont des fonctions d'assistance qui sont des wrappers sur l'API `LineageQuery` pour faciliter l'exploitation de certaines requêtes de lignée. L'exemple suivant montre comment utiliser cette fonction d'assistance.  

```
# Find all the datasets associated with this endpoint

datasets = []
dataset_artifacts = endpoint_context.dataset_artifacts()
for dataset in dataset_artifacts:
    datasets.append(dataset.source.source_uri)
print("Datasets : ", datasets)

# Find the training jobs associated with the endpoint
training_job_artifacts = endpoint_context.training_job_arns()
training_jobs = []
for training_job in training_job_artifacts:
    training_jobs.append(training_job)
print("Training Jobs : ", training_jobs)

# Get the ARN for the pipeline execution associated with this endpoint (if any)
pipeline_executions = endpoint_context.pipeline_execution_arn()
if pipeline_executions:
    for pipeline in pipelines_executions:
        print(pipeline)

# Here we use the `ModelArtifact` class to find all the datasets and endpoints associated with the model

dataset_artifacts = model_artifact.dataset_artifacts()
endpoint_contexts = model_artifact.endpoint_contexts()

datasets = [dataset.source.source_uri for dataset in dataset_artifacts]
endpoints = [endpoint.source.source_uri for endpoint in endpoint_contexts]

print("Datasets associated with this model : ")
pp.pprint(datasets)

print("Endpoints associated with this model : ")
pp.pprint(endpoints)

# Here we use the `DatasetArtifact` class to find all the endpoints hosting models that were trained with a particular dataset
# Find the artifact associated with the dataset

dataset_artifact_arn = list(Artifact.list(source_uri=training_data))[0].artifact_arn
dataset_artifact = DatasetArtifact.load(artifact_arn=dataset_artifact_arn)

# Find the endpoints that used this training dataset
endpoint_contexts = dataset_artifact.endpoint_contexts()
endpoints = [endpoint.source.source_uri for endpoint in endpoint_contexts]

print("Endpoints associated with the training dataset {}".format(training_data))
pp.pprint(endpoints)
```

**Example Obtention d’une visualisation de graphique de lignée**  
Une classe d'assistance `Visualizer` est fournie dans l'exemple de bloc-notes [visualizer.py](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-lineage/visualizer.py) pour aider à tracer le graphique de lignée. Lorsque la réponse de la requête est rendue, un graphique avec les relations de lignée du `StartArns` s’affiche. À partir du `StartArns`, la visualisation affiche les relations avec les autres entités de la lignée renvoyées dans l’action d’API `query_lineage`.  

```
# Graph APIs
# Here we use the boto3 `query_lineage` API to generate the query response to plot.

from visualizer import Visualizer

query_response = sm_client.query_lineage(
    StartArns=[endpoint_context.context_arn], Direction="Ascendants", IncludeEdges=True
)

viz = Visualizer()
viz.render(query_response, "Endpoint")
        
        query_response = sm_client.query_lineage(
    StartArns=[model_artifact.artifact_arn], Direction="Ascendants", IncludeEdges=True
)
viz.render(query_response, "Model")
```