Rastreamentos de pesquisa programaticamente

Pesquise e analise rastros programaticamente usando mlflow.search_traces(). Essa função pode consultar rastreamentos armazenados no servidor MLflow Acompanhament, em tabelas de inferência ou em tabelas Unity Catalog . Você pode selecionar subconjuntos de traços para analisar ou criar um conjunto de dados de avaliação.

API`mlflow.search_traces()`

Python
def mlflow.search_traces(
    experiment_ids: list[str] | None = None,
    filter_string: str | None = None,
    max_results: int | None = None,
    order_by: list[str] | None = None,
    extract_fields: list[str] | None = None,
    run_id: str | None = None,
    return_type: Literal['pandas', 'list'] | None = None,
    model_id: str | None = None,
    sql_warehouse_id: str | None = None,
    include_spans: bool = True,
    locations: list[str] | None = None,
) -> pandas.DataFrame | list[Trace]

mlflow.search_traces() permite filtrar e selecionar dados ao longo de algumas dimensões:

Filtrar por uma string de consulta
Filtrar por locais: experimento, execução, modelo ou esquema Unity Catalog
Limitar dados: número máximo de resultados, incluir ou excluir intervalos.
Ajustar o formato do valor de retorno: formato dos dados, ordem dos dados

search_traces() retorna um DataFrame Pandas ou uma lista de objetos Trace , que podem então ser analisados posteriormente ou remodelados em um conjunto de dados de avaliação. Consulte os detalhes do esquema desses tipos de retorno.

Consulte a documentação da APImlflow.search_traces() para obter detalhes completos.

Parâmetros`mlflow.search_traces()`

Categoria	`parameter: type`	Descrição	Exemplo
Filtrar por strings de consulta	`filter_string: str`	Consulte a sintaxe da consulta de pesquisa, incluindo os filtros e comparadores suportados.	`attributes.status = 'OK' AND tags.environment = 'production'`
Filtrar por localização	`locations: list[str]`	Este argumento pode ser uma lista de IDs de experimentos ou locais do Unity Catalog `catalog.schema` para filtragem. Use isso para pesquisar rastreamentos armazenados em tabelas de inferência ou Unity Catalog .	`['591498498138889', '782498488231546']` ou `['my_catalog.my_schema']`
	`run_id: str`	ID de execução do MLflow	`35464a26b0144533b09d8acbb4681985`
	`model_id: str`	ID do modelo MLflow	`acc4c426-5dd7-4a3a-85de-da1b22ce05f1`
Dados limitados	`max_results: int`	Número máximo de registros (linhas) a serem retornados	`100`
	`include_spans: bool`	Incluir ou excluir intervalos dos resultados. Os intervalos incluem detalhes de rastreamento e podem aumentar consideravelmente o tamanho dos resultados.	`True`
Formato do valor de retorno	`order_by: list[str]`	Consulte a sintaxe e as chaves suportadas.	`["timestamp_ms DESC", "status ASC"]`
	`return_type: Literal['pandas', 'list']`	Esta função pode retornar um DataFrame Pandas ou uma lista de objetos `Trace` . Veja os detalhes do esquema.	`'pandas'`
Descontinuado	`experiment_ids: list[str]`	Use `locations` em vez disso.
	`extract_fields: list[str]`	Selecione os campos no DataFrame retornado ou rastreie os objetos.
	`sql_warehouse_id: str`	Use a variável de ambiente`MLFLOW_TRACING_SQL_WAREHOUSE_ID` em vez disso.

Melhores práticas

Argumentos de palavra-chave

Sempre use argumentos nomeados (palavra-chave) com mlflow.search_traces(). Permite argumentos posicionais, mas os argumentos funcionais estão em evolução.

Boa prática: mlflow.search_traces(filter_string="attributes.status = 'OK'")

Má prática: mlflow.search_traces([], "attributes.status = 'OK'")

`filter_string` armadilhas

Ao pesquisar usando o argumento filter_string para mlflow.search_traces(), lembre-se de:

Use os prefixos: attributes., tags., ou metadata.
Use crases (`) se os nomes tag ou atributos contiverem pontos: tags.`mlflow.traceName`
Use apenas aspas simples: 'value' não "value"
Use o timestamp Unix (em milissegundos) para hora: 1749006880539 não datas.
Use somente o comando AND: Não há suporte para OR.

Consulte a sintaxe da consulta de pesquisa para obter mais detalhes.

Integração SQL warehouse

mlflow.search_traces() Opcionalmente, é possível usar um SQL warehouse Databricks para melhorar o desempenho em grandes conjuntos de dados de rastreamento em tabelas de inferência ou tabelas Unity Catalog . Especifique o ID do seu SQL warehouse usando a variável de ambiente MLFLOW_TRACING_SQL_WAREHOUSE_ID .

Execute consultas de rastreamento usando um data warehouse Databricks SQL para melhorar o desempenho em grandes conjuntos de dados de rastreamento:

Python
import os

os.environ['MLFLOW_TRACING_SQL_WAREHOUSE_ID'] = 'fa92bea7022e81fb'

# Use SQL warehouse for better performance
traces = mlflow.search_traces(
    filter_string="attributes.status = 'OK'",
    locations=['my_catalog.my_schema'],
)

Paginação

mlflow.search_traces() Retorna os resultados na memória, o que funciona bem para conjuntos de resultados menores. Para lidar com grandes conjuntos de resultados, use MlflowClient.search_traces() pois ele suporta paginação.

Próximos passos

Tutorial: Pesquisa programática de rastros - execução de um conjunto de exemplos simples de mlflow.search_traces()
Tutorial: Rastrear e analisar usuários e ambientes - execução de um exemplo de adição de metadados de contexto a rastreamentos e análise dos resultados.
Exemplos: Análise de vestígios - Veja diversos exemplos de análise de vestígios.
Criar um conjunto de dados de avaliação - Converter os traços consultados em um conjunto de dados de teste

APImlflow.search_traces()​

Parâmetrosmlflow.search_traces()​

Melhores práticas​

Argumentos de palavra-chave​

filter_string armadilhas​

Integração SQL warehouse​

Paginação​

Próximos passos​