Acesso programático a rastreamentos
Pesquise, leia e analise rastreamentos programaticamente. Use mlflow.search_traces() para query rastreamentos armazenados em tabelas do Unity Catalog, no servidor de acompanhamento do MLflow ou em tabelas de inferência — e, para rastreamentos no Unity Catalog, query as tabelas Delta diretamente com SQL. Assim que tiver um rastreamento, leia o modelo de objeto dele — metadados, intervalos, avaliações e uso de tokens — para inspecionar o que aconteceu. Você pode selecionar subconjuntos de rastreamentos para analisar ou criar datasets de avaliação.
APImlflow.search_traces()
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.
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 |
| Descrição | Exemplo |
|---|---|---|---|
Filtrar por strings de consulta |
| Consulte a sintaxe de consulta de pesquisa para obter informações sobre os filtros e comparadores compatíveis. |
|
Filtrar por localização |
| Este argumento pode ser uma lista de IDs de experimentos ou locais do Unity Catalog |
|
| ID de execução do MLflow |
| |
| ID do modelo MLflow |
| |
Dados limitados |
| Número máximo de registros (linhas) a serem retornados |
|
| Incluir ou excluir intervalos dos resultados. Os intervalos incluem detalhes de rastreamento e podem aumentar consideravelmente o tamanho dos resultados. |
| |
Formato do valor de retorno |
| Consulte a sintaxe e as chaves suportadas. |
|
| Esta função pode retornar um DataFrame Pandas ou uma lista de objetos |
| |
Descontinuado |
| Use | |
| Selecione os campos no DataFrame retornado ou rastreie os objetos. | ||
| Use a variável de ambiente |
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.
Os filtros marcados como (somente UC) são compatíveis apenas com rastreamentos MLflow armazenados no Unity Catalog. Consulte Armazenar rastreamentos do OpenTelemetry no Unity Catalog.
Tipo de campo | Campos | Comparadores | Exemplo |
|---|---|---|---|
Rastrear estado |
|
|
|
Registros de data e hora de rastreamento |
|
|
|
IDs de rastreamento |
|
|
|
campos de strings |
|
|
|
Conteúdo da solicitação e da resposta (somente UC) |
|
|
|
Contagem de tokens (somente UC) |
|
|
|
Instruções relacionadas |
|
|
|
Nome do span, tipo, status e nome do serviço (apenas UC) |
|
|
|
Atributos de extensão OTel (somente UC) |
|
|
|
Tags |
|
Para rastreamentos MLflow armazenados em um experimento (não no Unity Catalog), somente |
|
Metadados |
|
Para rastreamentos MLflow armazenados em um experimento (não no Unity Catalog), somente |
|
Feedback (somente para membros da UC) |
|
|
|
Expectativas (somente para a UC) |
|
|
|
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 |
|---|---|---|---|
| Compatível (somente UC) | Não suportado | Utilize esses campos para filtrar o conteúdo serializado de solicitações e respostas. |
| Compatível (somente UC) | Não suportado | Filtrar rastros pela contagem total de tokens. |
| Compatível (somente UC) | Não suportado | Filtrar rastreamentos por atributos de intervalo do OpenTelemetry. |
| Não suportado | Compatível (somente com armazenamento SQLAlchemy) | OSS expõe |
| Não suportado | Suportado (mapeado para a tag de prompts vinculados) | No Databricks, use o campo de nível superior |
| Não suportado | Apoiado | No Databricks, use |
| 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.
query tabelas de rastreamento com SQL
Quando os rastreamentos são armazenados no Unity Catalog, você pode consultá-los com o Databricks SQL, além do SDK. O serviço MLflow armazena dados de intervalo em tabelas compatíveis com OpenTelemetry e cria automaticamente views do Databricks SQL que transformam esses dados no formato do MLflow. Para configurar o armazenamento de rastreamentos do Unity Catalog, consulte Armazenar rastreamentos do OpenTelemetry no Unity Catalog.
A Databricks recomenda consultar as views (ou usar o SDK) em vez das tabelas OpenTelemetry subjacentes, cujos esquemas podem mudar com o tempo. Para grandes volumes de rastreamento, o desempenho da view pode se degradar: crie uma materialized view sobre as views e atualize-a de forma incremental, ou use o SDK para obter o melhor desempenho em dados recentes.
{table_prefix}_trace_unified
Uma view unificada de todos os dados de rastreamento, agrupados por ID de rastreamento. Cada linha contém os dados brutos de span mais os metadados de rastreamento (tags, metadados e avaliações do MLflow). Colunas de nível superior:
trace_id: STRING
client_request_id: STRING
request_time: TIMESTAMP
state: STRING
execution_duration_ms: DOUBLE
request: STRING
response: STRING
trace_metadata: VARIANT
tags: MAP<STRING, STRING>
spans: LIST<STRUCT> # per-span records: name, kind, timing, attributes, status, events, links
assessments: LIST<STRUCT> # feedback and expectation records with source, value, rationale, metadata
A coluna trace_metadata e os campos do span attributes são VARIANT. Leia-os com a sintaxe de caminho de dois pontos e faça o cast para o tipo necessário, em vez de usar a pesquisa de key de mapa:
SELECT spans[0].attributes:`mlflow.spanInputs`::STRING FROM my_catalog.my_schema.my_prefix_trace_unified
{table_prefix}_trace_metadata
Contém apenas as tags do MLflow, os metadados e as avaliações agrupadas por ID de rastreio. Tem melhor desempenho do que a view unificada quando você precisa de dados de anotação do MLflow, mas não de dados de intervalo. Colunas: trace_id, client_request_id, tags, trace_metadata e assessments (mesma estrutura que na view unificada).
Formatos de dados de anotação
As entidades de anotação do MLflow (metadados, tags, avaliações e links de execução) também são armazenadas na tabela {table_prefix}_otel_annotations, com uma linha por entidade com um annotation_type tipado (METADATA, TAG, FEEDBACK, EXPECTATION ou RUN_LINK). A tabela é apenas de anexação (append-only) com exclusões lógicas, portanto, faça a desduplicação na recuperação: pegue a linha mais recente por annotation_id (ordene por updated_at de forma decrescente) e descarte as linhas em que deleted_at estiver definido. As colunas value e metadata são VARIANT (JSON). Para avaliações, os metadados fornecidos pelo usuário ficam junto com as key internas do MLflow (com prefixo mlflow.); ignore as key internas ao ler os metadados do usuário.
Analisar o desempenho da query
Para diagnosticar querys lentas, inspecione os perfis de query no history de querys do SQL warehouse: abra a página de SQL warehouses , selecione seu warehouse e clique em History de querys . Filtre por queries que tenham o MLflow como origem, abra uma query para ver seu perfil e verifique:
- Scheduling time : um tempo de agendamento alto significa que as queries estão na fila devido à alta carga do warehouse. Switch to a different warehouse in the MLflow UI, or configure a different warehouse in your client.
- Desempenho geral da query : para queries consistentemente lentas, use um SQL warehouse maior, restrinja os limites de
trace.timestamp_mse remova outros predicados de filtro sempre que possível.
Ler dados de rastreamento
Um Trace do MLflow tem dois componentes:
Para ver o modelo de objeto e o esquema de rastreamento completos, consulte a referência do modelo de dados de rastreamento.
Propriedades de metadados básicos
# Primary identifiers
print(f"Trace ID: {trace.info.trace_id}")
print(f"Client Request ID: {trace.info.client_request_id}")
# Status information
print(f"State: {trace.info.state}") # OK, ERROR, IN_PROGRESS
# Request/response previews (truncated)
print(f"Request preview: {trace.info.request_preview}")
print(f"Response preview: {trace.info.response_preview}")
Local de armazenamento e experimento
location = trace.info.trace_location
print(f"Location type: {location.type}")
# Stored in Unity Catalog (recommended)
if location.uc_table_prefix:
print(f"UC location: {location.uc_table_prefix.full_table_prefix}")
# Stored in an MLflow experiment
if location.mlflow_experiment:
print(f"Experiment ID: {trace.info.experiment_id}")
# Stored in a Databricks inference table
if location.inference_table:
print(f"Table: {location.inference_table.full_table_name}")
O experimento é o ponto de entrada da IU, independentemente do backend. Use trace.info.experiment_id para abrir o rastreamento na IU do MLflow, mesmo quando ele estiver armazenado no Unity Catalog.
Visualizações de solicitação e resposta
As propriedades request_preview e response_preview fornecem resumos truncados dos dados completos de solicitação e resposta, para que você possa entender o que aconteceu sem carregar as cargas úteis completas.
request_preview = trace.info.request_preview
response_preview = trace.info.response_preview
# Full request/response data (see below)
full_request = trace.data.request
full_response = trace.data.response
Propriedades relacionadas ao tempo
# Timestamps (milliseconds since epoch)
print(f"Start time (ms): {trace.info.request_time}")
print(f"Timestamp (ms): {trace.info.timestamp_ms}") # Alias for request_time
# Duration
print(f"Execution duration (ms): {trace.info.execution_duration}")
# Convert to human-readable format
import datetime
start_time = datetime.datetime.fromtimestamp(trace.info.request_time / 1000)
print(f"Started at: {start_time}")
Tags e metadados
# Tags (mutable, can be updated after creation)
for key, value in trace.info.tags.items():
print(f" {key}: {value}")
print(f"Environment: {trace.info.tags.get('environment')}")
# Trace metadata (immutable, set at creation)
for key, value in trace.info.trace_metadata.items():
print(f" {key}: {value}")
Informações de uso de tokens
O MLflow Tracing pode rastrear o uso de tokens de chamadas de LLM, usando contagens de tokens retornadas por APIs de provedores de LLM.
# Get aggregated token usage (if available)
token_usage = trace.info.token_usage
if token_usage:
print(f"Input tokens: {token_usage.get('input_tokens')}")
print(f"Output tokens: {token_usage.get('output_tokens')}")
print(f"Total tokens: {token_usage.get('total_tokens')}")
Como você monitora o uso de tokens depende do provedor de LLM:
Cenário | Como monitorar o uso de tokens |
|---|---|
Use o cliente OpenAI para verificar se o MLflow Tracing rastreia automaticamente o uso de tokens. | |
Provedores de LLM com suporte nativo ao MLflow Tracing | Consulte a página de integração do provedor em Integrações do MLflow Tracing para determinar se o acompanhamento nativo de tokens é compatível. |
Provedores sem suporte nativo ao MLflow Tracing | Registre manualmente o uso de tokens usando |
Monitore múltiplos endpoints em sua plataforma de AI. | Use o acompanhamento de uso do AI Gateway para registrar o uso de tokens em tabelas do sistema em endpoints de serving. |
Avaliações
Encontrar avaliações com search_assessments():
# Get all assessments
all_assessments = trace.search_assessments()
# Search by name
helpfulness = trace.search_assessments(name="helpfulness")
if helpfulness:
assessment = helpfulness[0]
print(f"Helpfulness: {assessment.value}")
print(f"Source: {assessment.source.source_type} - {assessment.source.source_id}")
print(f"Rationale: {assessment.rationale}")
# Search by type
feedback_only = trace.search_assessments(type="feedback")
expectations_only = trace.search_assessments(type="expectation")
# Search by span ID
span_assessments = trace.search_assessments(span_id=retriever_span.span_id)
# Include overridden assessments
all_including_invalid = trace.search_assessments(all=True)
Acessar detalhes da avaliação:
for assessment in trace.info.assessments:
print(f"Assessment: {assessment.name}")
print(f" Type: {type(assessment).__name__}")
print(f" Value: {assessment.value}")
print(f" Source: {assessment.source.source_type.value}")
if assessment.rationale:
print(f" Rationale: {assessment.rationale}")
if assessment.metadata:
print(f" Metadata: {assessment.metadata}")
if assessment.error:
print(f" Error: {assessment.error}")
Trabalhar com intervalos
Os spans são os blocos de construção de rastreamentos, representando operações individuais ou unidades de trabalho. A classe Span representa spans imutáveis e concluídos recuperados de rastreamentos.
Acessar propriedades de intervalo
# Access all spans from a trace
spans = trace.data.spans
print(f"Total spans: {len(spans)}")
span = spans[0]
# Basic properties
print(f"Span ID: {span.span_id}")
print(f"Name: {span.name}")
print(f"Type: {span.span_type}")
print(f"Parent ID: {span.parent_id}") # None for root spans
# Timing (nanoseconds)
duration_ms = (span.end_time_ns - span.start_time_ns) / 1_000_000
print(f"Duration: {duration_ms:.2f}ms")
# Status
print(f"Status code: {span.status.status_code}")
# Inputs and outputs
print(f"Inputs: {span.inputs}")
print(f"Outputs: {span.outputs}")
Encontrar spans específicos
Use search_spans() para encontrar spans que correspondam a critérios específicos:
import re
from mlflow.entities import SpanType
# Search by exact name
retriever_spans = trace.search_spans(name="retrieve_documents")
# Search by regex pattern
tool_spans = trace.search_spans(name=re.compile(r".*_tool$"))
# Search by span type
chat_spans = trace.search_spans(span_type=SpanType.CHAT_MODEL)
llm_spans = trace.search_spans(span_type="CHAT_MODEL") # String also works
# Search by span ID
specific_span = trace.search_spans(span_id=retriever_spans[0].span_id)
# Combine criteria
tool_fact_check = trace.search_spans(
name="fact_check_tool",
span_type=SpanType.TOOL,
)
Atributos de span
from mlflow.tracing.constant import SpanAttributeKey
chat_span = trace.search_spans(span_type=SpanType.CHAT_MODEL)[0]
# Get all attributes
for key, value in chat_span.attributes.items():
print(f" {key}: {value}")
# Get a specific attribute
specific_attr = chat_span.get_attribute("custom_attribute")
# Access chat-specific attributes using SpanAttributeKey
messages = chat_span.get_attribute(SpanAttributeKey.CHAT_MESSAGES)
tools = chat_span.get_attribute(SpanAttributeKey.CHAT_TOOLS)
# Access per-span token usage
input_tokens = chat_span.get_attribute("llm.token_usage.input_tokens")
output_tokens = chat_span.get_attribute("llm.token_usage.output_tokens")
Dados de solicitação e resposta
import json
# Get root span request/response
request_json = trace.data.request
response_json = trace.data.response
# Parse JSON strings
if request_json:
request_data = json.loads(request_json)
if response_json:
response_data = json.loads(response_json)
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., oumetadata. - 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:
1749006880539nã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
Um Databricks SQL warehouse é necessário para ler rastreamentos armazenados em experimentos do Unity Catalog. Defina MLFLOW_TRACING_SQL_WAREHOUSE_ID antes de chamar mlflow.search_traces() ou mlflow.get_trace() em um experimento com suporte do Unity Catalog. Sem essa variável de ambiente definida, a leitura falha com SQL warehouse ID is required for accessing traces in UC tables. Consulte Armazenar rastreamentos no Unity Catalog para a configuração.
Para datasets grandes que não sejam do Unity Catalog, como tabelas de inferência, um SQL warehouse é opcional e melhora o desempenho da query.
import os
os.environ['MLFLOW_TRACING_SQL_WAREHOUSE_ID'] = 'fa92bea7022e81fb'
# Required for UC-backed experiments. Improves performance for large non-UC datasets.
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.
Recursos adicionais
- Encontre problemas em rastreamentos — Deixe o MLflow detectar problemas em seus rastreamentos.
- Referência do modelo de dados de rastreamento — O modelo de objeto de rastreamento completo: spans, tipos de span e ciclo de vida.
- Enriquecer rastreamentos: tags, contexto e feedback - Enriqueça rastreamentos com tags, metadados e contexto para uma pesquisa mais rica.
- Criar datasets de avaliação - Converta rastreamentos consultados em datasets de teste.
Próximo passo: Coletar feedback e criar datasets