Consultar entidades de linhagem

A Amazon gera SageMaker automaticamente gráficos de entidades de linhagem à medida que você as usa. Você pode consultar esses dados para responder a várias perguntas. 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 (Jakarta), 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 relacõ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.

Tópicos

Conceitos básicos da consulta de entidades de linhagem

Conceitos básicos da consulta de entidades de linhagem

A maneira mais fácil de começar é por meio do:

Amazon SageMaker SDK para Python, que definiu muitos casos de uso comuns.
Para um notebook que demonstra como usar as APIs do SageMaker Lineage para consultar relacionamentos no gráfico de linhagem, consulte .ipynb. sagemaker-lineage-multihop-queries

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

exemplo 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)

exemplo 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)

exemplo 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)

exemplo 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)

exemplo 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)

exemplo Usando `LineageQueryDirectionEnum.BOTH` para encontrar relacõ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)

exemplo Instruções em `LineageQuery` - `ASCENDANTS` vs. `DESCENDANTS`

Para entender a direção no gráfico de linhagem, use o seguinte gráfico de relacõ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)

exemplo 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)

exemplo Obtendo uma visualização do gráfico de linhagem

Uma classe auxiliar Visualizer é fornecida no exemplo de notebook 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 relacõ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")

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Crie entidades manualmente

Monitoramento entre contas