As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Consultar entidades de linhagem
<a name="querying-lineage-entities"></a>

A Amazon SageMaker AI gera automaticamente gráficos de entidades de linhagem à medida que você as usa. Você pode consultar esses dados para responder a várias perguntas. Veja a seguir instruções sobre como consultar esses dados no SDK para Python. 

Para obter informações sobre como visualizar uma linhagem de modelo registrada no Amazon SageMaker Studio, consulte[Visualizar detalhes da linhagem de modelo no Studio](model-registry-lineage-view-studio.md).

Você pode consultar suas entidades de linhagem para:
+ Recupere todos os conjuntos de dados usados na criação de um modelo.
+ Recupere todos os trabalhos que foram usados na criação de um endpoint.
+ Recupere todos os modelos que usam um conjunto de dados.
+ Recupere todos os endpoints que usam um modelo.
+ Recupere quais endpoints são derivados de um determinado conjunto de dados.
+ Recupere a execução do pipeline que criou um trabalho de treinamento.
+ Recupere as relações entre entidades para investigação, governança e reprodutibilidade.
+ Recupere todos os testes posteriores que usam o artefato.
+ Recupere todos os testes iniciais que usam o artefato.
+ Recupere uma lista de artefatos que usam o uri do S3 fornecido.
+ Recupere artefatos upstream que usam o artefato do conjunto de dados.
+ Recupere artefatos posteriores que usam o artefato do conjunto de dados.
+ Recupere conjuntos de dados que usam o artefato de imagem.
+ Recupere ações que usam o contexto.
+ Recupere trabalhos de processamento que usam o endpoint.
+ Recupere trabalhos de processamento que usam o endpoint.
+ Recupere componentes de teste que usam o endpoint.
+ Recupere o ARN para a execução do pipeline associado ao grupo de pacotes do modelo.
+ Recupere todos os artefatos que usam a ação.
+ Recupere todos os conjuntos de dados upstream que usam a ação de aprovação do pacote modelo.
+ Recupere o pacote do modelo da ação de aprovação do pacote do modelo.
+ Recupere contextos de endpoint downstream que usam o endpoint.
+ Recupere o ARN para a execução do pipeline associado ao componente de teste.
+ Recupere conjuntos de dados que usam o componente de teste.
+ Recupere modelos que usam o componente de teste.
+ Explore sua linhagem para visualização.

**Limitações**
+ A consulta de linhagem não está disponível nas seguintes regiões:
  + África (Cidade do Cabo), af-south
  + Ásia-Pacífico (Jacarta), ap-southeast-3
  + Ásia-Pacífico (Osaka) - ap-northeast-3
  + Europa (Milão),eu-south-1
  + Europa (Espanha), eu-south-2
  + Israel (Tel Aviv): il-central-1
+ A profundidade máxima de relações a serem descobertos está atualmente limitada a 10.
+ A filtragem é limitada às seguintes propriedades: data da última modificação, data de criação, tipo e tipo de entidade de linhagem. 

**Topics**
+ [Conceitos básicos da consulta de entidades de linhagem](#querying-lineage-entities-getting-started)

## Conceitos básicos da consulta de entidades de linhagem
<a name="querying-lineage-entities-getting-started"></a>

A maneira mais fácil de começar é por meio do:
+ [Amazon SageMaker AI SDK para Python](https://github.com/aws/sagemaker-python-sdk/blob/master/src/sagemaker/lineage/artifact.py#L397), que definiu muitos casos de uso comuns.
+ [Para um caderno que demonstra como usar o SageMaker AI Lineage APIs para consultar relacionamentos no gráfico de linhagem, consulte .ipynb. sagemaker-lineage-multihop-queries](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-lineage/sagemaker-lineage-multihop-queries.ipynb)

Os exemplos a seguir mostram como usar `LineageQuery` e criar consultas `LineageFilter` APIs para responder perguntas sobre o gráfico de linhagem e extrair relacionamentos de entidades para alguns casos de uso.

**Example Usando a API `LineageQuery` para encontrar associações 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 Encontre todos os conjuntos de dados associados a um endpoint**  

```
# 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 Encontre os modelos associados a um endpoint**  

```
# 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 Encontre os componentes do teste associados ao endpoint**  

```
# 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 Mudando o ponto focal da linhagem**  
Os `LineageQuery` podem ser modificados para serem diferentes `start_arns`, o que altera o ponto focal da linhagem. Além disso, é `LineageFilter` possível usar várias fontes e entidades para expandir o escopo da consulta.  
A seguir, usamos o modelo como ponto focal da linhagem e encontramos os endpoints e conjuntos de dados associados a ele.  

```
# 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 Usando `LineageQueryDirectionEnum.BOTH` para encontrar relações ascendentes e descendentes**  
Quando a direção é definida como `BOTH`, a consulta percorre o gráfico para encontrar relações ascendentes e descendentes. Essa travessia ocorre não apenas no nó inicial, mas em cada nó visitado. Por exemplo, se um trabalho de treinamento for executado duas vezes e os dois modelos gerados pelo trabalho de treinamento forem implantados nos endpoints, o resultado da consulta com a direção definida como `BOTH` mostrará os dois endpoints. Isso ocorre porque a mesma imagem é usada para treinar e implantar o modelo. Como a imagem é comum ao modelo, o `start_arn` e os dois endpoints aparecem no resultado da 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 Instruções em `LineageQuery` - `ASCENDANTS` vs. `DESCENDANTS`**  
Para entender a direção no gráfico de linhagem, use o seguinte gráfico de relações de entidades - Conjunto de dados -> Trabalho de treinamento -> Modelo -> Endpoint  
O endpoint é descendente do modelo e o modelo é descendente do conjunto de dados. Da mesma forma, o modelo é um ascendente do endpoint. O parâmetro `direction` pode ser usado para especificar se a consulta deve retornar entidades descendentes ou ascendentes da entidade em `start_arns`. Se o `start_arns` contiver um modelo e a direção for `DESCENDANTS`, a consulta retornará o endpoint. Se a direção for `ASCENDANTS`, a consulta retornará o conjunto de dados.  

```
# 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 Funções auxiliares do SDK para facilitar as consultas de linhagem**  
As classes `EndpointContext`, `ModelArtifact` e `DatasetArtifact` têm funções auxiliares que são envolventes na API `LineageQuery` para facilitar o aproveitamento de determinadas consultas de linhagem. O exemplo a seguir mostra como usar essas funções auxiliares.  

```
# 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 Obtendo uma visualização do gráfico de linhagem**  
Uma classe auxiliar `Visualizer` é fornecida no exemplo de caderno [visualizer.py](https://github.com/aws/amazon-sagemaker-examples/blob/master/sagemaker-lineage/visualizer.py) para ajudar a traçar o gráfico de linhagem. Quando a resposta da consulta é renderizada, um gráfico com as relações de linhagem do `StartArns` é exibido. A partir `StartArns` da visualização, mostra as relações com as outras entidades de linhagem retornadas na ação da 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")
```