Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

# Consulta de entidades de linaje
<a name="querying-lineage-entities"></a>

Amazon SageMaker AI genera automáticamente gráficos de entidades de linaje a medida que las usa. Puede consultar estos datos para responder a una variedad de preguntas. A continuación, se proporcionan instrucciones sobre cómo consultar estos datos en el SDK para Python. 

Para obtener información sobre cómo ver un linaje de modelos registrado en Amazon SageMaker Studio, consulte[Visualización de los detalles del linaje del modelo en Studio](model-registry-lineage-view-studio.md).

Puede consultar las entidades de su linaje para:
+ Recuperar todos los conjuntos de datos que se utilizaron en la creación de un modelo.
+ Recuperar todos los trabajos necesarios para la creación de un punto de conexión.
+ Recuperar todos los modelos que utilizan un conjunto de datos.
+ Recuperar todos los puntos de conexión que utilizan un modelo.
+ Recuperar qué puntos de conexión se derivan de un determinado conjunto de datos.
+ Recuperar la ejecución de la canalización que creó un trabajo de entrenamiento.
+ Recuperar las relaciones entre las entidades para la investigación, la gobernanza y la reproducibilidad.
+ Recuperar todas las pruebas posteriores que utilizan el artefacto.
+ Recuperar todas las pruebas anteriores que utilizan el artefacto.
+ Recuperar una lista de artefactos que utilizan el URI de S3 proporcionado.
+ Recuperar los artefactos anteriores que utilizan el artefacto del conjunto de datos.
+ Recuperar los artefactos posteriores que utilizan el artefacto del conjunto de datos.
+ Recuperar los conjuntos de datos que utilizan el artefacto de imagen.
+ Recuperar las acciones que utilizan el contexto.
+ Recuperar los trabajos de procesamiento que utilizan el punto de conexión.
+ Recuperar los trabajos de transformación que utilizan el punto de conexión.
+ Recuperar los componentes de prueba que utilizan el punto de conexión.
+ Recuperar el ARN de la ejecución de la canalización asociada al grupo de paquetes de modelos.
+ Recuperar todos los artefactos que utilizan la acción.
+ Recuperar todos los conjuntos de datos originales que utilizan la acción de aprobación del paquete de modelos.
+ Recuperar el paquete de modelos de la acción de aprobación del paquete de modelos.
+ Recuperar los contextos de punto de conexión posteriores que utilizan el punto de conexión.
+ Recuperar el ARN de la ejecución de la canalización asociada al componente de prueba.
+ Recuperar los conjuntos de datos que utilizan el componente de prueba.
+ Recuperar los modelos que utilizan el componente de prueba.
+ Explorar su linaje para visualizarlo.

**Limitaciones**
+ La consulta de linaje no está disponible en las siguientes regiones:
  + África (Ciudad del Cabo): af-south
  + Asia-Pacífico (Yakarta) (ap-southeast-3)
  + Asia-Pacífico (Osaka) ap-northeast-3
  + Europa (Milán) (eu-south-1)
  + Europa (España): eu-south-2
  + Israel (Tel Aviv): il-central-1
+ La profundidad máxima de las relaciones por detectar está limitada actualmente a 10.
+ El filtrado se limita a las siguientes propiedades: fecha de la última modificación, fecha de creación, tipo y tipo de entidad de linaje. 

**Topics**
+ [Introducción a la consulta de entidades de linaje](#querying-lineage-entities-getting-started)

## Introducción a la consulta de entidades de linaje
<a name="querying-lineage-entities-getting-started"></a>

La forma más sencilla para empezar es a través de:
+ [Amazon SageMaker AI SDK para Python](https://github.com/aws/sagemaker-python-sdk/blob/master/src/sagemaker/lineage/artifact.py#L397), que ha definido muchos casos de uso comunes.
+ [Para ver un cuaderno que muestre cómo usar SageMaker AI Lineage APIs para consultar las relaciones en el gráfico de linaje, consulte sagemaker-lineage-multihop-queries .ipynb.](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-lineage/sagemaker-lineage-multihop-queries.ipynb)

Los siguientes ejemplos muestran cómo usar el gráfico de linaje `LineageQuery` y cómo construir consultas `LineageFilter` APIs para responder a preguntas sobre el gráfico de linaje y extraer las relaciones entre entidades para algunos casos de uso.

**Example Uso de la API `LineageQuery` para buscar asociaciones de entidades**  

```
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 Buscar todos los conjuntos de datos asociados a un punto de conexión**  

```
# 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 Buscar los modelos asociados a un punto de conexión**  

```
# 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 Buscar los componentes de prueba asociados al punto de conexión**  

```
# 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 Cambiar el punto focal del linaje**  
`LineageQuery` se puede modificar para que tenga diferentes `start_arns`, lo que cambia el punto focal del linaje. Además, `LineageFilter` pueden utilizarse varios orígenes y entidades para ampliar el alcance de la consulta.  
A continuación, utilizamos el modelo como punto focal del linaje y buscamos los puntos de conexión y los conjuntos de datos asociados a él.  

```
# 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 Uso de `LineageQueryDirectionEnum.BOTH` para encontrar relaciones ascendentes y descendentes**  
Cuando la dirección está establecida en `BOTH`, la consulta recorre el gráfico para encontrar las relaciones ascendentes y descendentes. Este recorrido se realiza no solo desde el nodo inicial, sino también desde cada nodo visitado. Por ejemplo, si un trabajo de entrenamiento se ejecuta dos veces y los dos modelos generados por el trabajo de entrenamiento se despliegan en los puntos de conexión, el resultado de la consulta con la dirección establecida en `BOTH` muestra ambos puntos de conexión. Esto se debe a que se utiliza la misma imagen para entrenar e implementar el modelo. Como la imagen es común al modelo, el `start_arn` y ambos puntos de conexión aparecen en el resultado de la consulta.  

```
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 Direcciones en `LineageQuery`: `ASCENDANTS` vs. `DESCENDANTS`**  
Para entender la dirección del gráfico de linaje, tome el siguiente gráfico de relación entre entidades: Conjunto de datos -> Trabajo de entrenamiento -> Modelo -> Punto de conexión  
El punto de conexión es un descendiente del modelo y el modelo es un descendiente del conjunto de datos. Del mismo modo, el modelo es un ascendente del punto de conexión. El parámetro `direction` se puede usar para especificar si la consulta debe devolver entidades descendientes o ascendentes de la entidad en `start_arns`. Si `start_arns` contiene un modelo y la dirección es `DESCENDANTS`, la consulta devuelve el punto de conexión. Si la dirección es `ASCENDANTS`, la consulta devuelve el conjunto de datos.  

```
# 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 Funciones auxiliares del SDK que facilitan las consultas de linaje**  
Las clases `EndpointContext`, `ModelArtifact` y `DatasetArtifact` tienen funciones auxiliares que se integran en la API `LineageQuery` para facilitar el uso de determinadas consultas de linaje. El siguiente ejemplo muestra cómo utilizar esta función auxiliar.  

```
# 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 Obtener una visualización de un gráfico de linaje**  
En el ejemplo de cuaderno [visualizer.py](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-lineage/visualizer.py) se proporciona una clase auxiliar `Visualizer` para ayudar a trazar el gráfico de linaje. Cuando se representa la respuesta a la consulta, se muestra un gráfico con las relaciones de linaje de `StartArns`. Desde el `StartArns` la visualización muestran las relaciones con las demás entidades de linaje devueltas en la acción de la 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")
```