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.

APImlflow.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.

nota

Databricks-gerenciar MLflow e OSS (código aberto software) MLflow compartilham a maior parte da sintaxe de consulta de pesquisa, mas têm algumas diferenças no nível do campo. Consulte a seção Diferenças em relação ao MLflow de código aberto para obter detalhes.

Parâmetrosmlflow.search_traces()

Categoria	parameter: type	Descrição	Exemplo
Filtrar por strings de consulta	filter_string: str	Consulte a sintaxe de consulta de pesquisa para obter informações sobre os filtros e comparadores compatíveis.	trace.status = 'OK' AND tag.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 ambienteMLFLOW_TRACING_SQL_WAREHOUSE_ID em vez disso.

Sintaxe de consulta de pesquisa

O argumento filter_string usa uma linguagem de consulta semelhante a SQL para filtrar rastreamentos. Os valores de string devem ser colocados entre aspas simples (por exemplo, trace.status = 'OK'), e os valores numéricos não devem ser colocados entre aspas (por exemplo, trace.execution_time_ms > 1000). Combine as condições com AND. O operador OR não é suportado.

Filtros e comparadores suportados

Os seguintes campos e comparadores são suportados no Databricks-gerenciar MLflow.

nota

Os filtros marcados como (somente UC) são compatíveis apenas com rastreamentos MLflow armazenados no Unity Catalog. Consulte Armazenar rastreamentos MLflow no Unity Catalog.

Tipo de campo	Campos	Comparadores	Exemplo
Rastrear estado	trace.status	=, !=	trace.status = 'OK'
Registros de data e hora de rastreamento	trace.timestamp_ms, trace.execution_time_ms, trace.end_time_ms (somente UC)	=, !=, >, <, >=, <=	trace.end_time_ms > 1762408895531
IDs de rastreamento	trace.run_id	=	trace.run_id = 'run_id'
campos de strings	trace.client_request_id (Apenas para a UC), trace.name	=, !=, LIKE, ILIKE, RLIKE	trace.name LIKE '%Generate%'
Conteúdo da solicitação e da resposta (somente UC)	trace.request, trace.response	=, !=, LIKE, ILIKE, RLIKE	trace.request LIKE '%weather%'
Contagem de tokens (somente UC)	trace.token_count	=, !=, >, <, >=, <=	trace.token_count > 1000
Instruções relacionadas	prompt	= (formato: 'name/version')	prompt = 'qa-system-prompt/4'
Nome, tipo e status do span (somente UC)	span.name, span.type, span.status	=, !=, LIKE, ILIKE, RLIKE	span.type RLIKE '^LLM'
Atributos de extensão OTel (somente UC)	span.attributes.<key>	=, !=, LIKE, ILIKE, RLIKE, IS NULL, IS NOT NULL	span.attributes.gen_ai.request.model = 'gpt-4'
Tags	tag.<key>	=, !=, LIKE, ILIKE, RLIKE, IS NULL, IS NOT NULL Para rastreamentos MLflow armazenados em um experimento (não no Unity Catalog), somente = e != são suportados.	tag.environment = 'production'
Metadados	metadata.<key>	=, !=, LIKE, ILIKE, RLIKE, IS NULL, IS NOT NULL Para rastreamentos MLflow armazenados em um experimento (não no Unity Catalog), somente = e != são suportados.	metadata.`mlflow.trace.user` = 'user_123'
Feedback (somente para membros da UC)	feedback.<name>	=, !=, LIKE, ILIKE, RLIKE	feedback.rating = 'excellent'
Expectativas (somente para a UC)	expectation.<name>	=, !=, LIKE, ILIKE, RLIKE	expectation.result = 'pass'

Diferenças em relação ao MLflow de código aberto

A sintaxe de consulta de pesquisa no Databricks-gerenciar MLflow segue de perto MLflowde código aberto, com as seguintes diferenças:

campo	Databricks-gerenciar MLflow	OSS MLflow	Notas
trace.request, trace.response	Compatível (somente UC)	Não suportado	Utilize esses campos para filtrar o conteúdo serializado de solicitações e respostas.
trace.token_count	Compatível (somente UC)	Não suportado	Filtrar rastros pela contagem total de tokens.
span.attributes.<key>	Compatível (somente UC)	Não suportado	Filtrar rastreamentos por atributos de intervalo do OpenTelemetry.
trace.text	Não suportado	Compatível (somente com armazenamento SQLAlchemy)	OSS expõe trace.text para pesquisa de texto completo em todo o conteúdo de rastreamento. No Databricks, use trace.request e trace.response para filtrar o conteúdo de rastreamento.
trace.prompt	Não suportado	Suportado (mapeado para a tag de prompts vinculados)	No Databricks, use o campo de nível superior prompt .
trace.request_id	Não suportado	Apoiado	No Databricks, use trace.client_request_id em vez disso.
issue.id	Não suportado	Apoiado	Filtrar rastreamentos vinculados a um ID de problema específico.

Pesquise por spans OpenTelemetry de terceiros

Para pesquisar rastros ingeridos de ferramentas OpenTelemetry de terceiros, como Langfuse, use o prefixo span.attributes.* em vez disso. Consulte Pesquisar rastros por atributos de intervalo OTel.

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="trace.status = 'OK'")

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

filter_string armadilhas

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

• Use os prefixos: trace., tag., ou metadata.
• Use crases (`) se os nomes tag ou atributos contiverem pontos: tag.`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 de consulta de pesquisa para obter a lista completa de campos e operadores compatíveis.

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="trace.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