Modelo de dados de rastreamento

Este documento fornece uma visão geral detalhada do modelo de dados do MLflow Trace. Entender esse modelo é key para aproveitar o MLflow Tracing para observabilidade e análise de seus aplicativos AI generativos.

MLflow Os rastreamentos são projetados para serem compatíveis com as especificações do OpenTelemetry , um padrão amplamente adotado pelas indústrias para observabilidade. Isso garante a interoperabilidade e permite que o MLflow Traces seja exportado e usado com outros sistemas compatíveis com o OpenTelemetry. MLflow aprimora o modelo básico do OpenTelemetry Span, definindo estruturas e atributos específicos para casos de uso do Generative AI, proporcionando um contexto mais rico e um entendimento mais profundo da qualidade e do desempenho.

Estrutura dos traços

Em um nível mais alto, um MLflow Trace é composto por dois objetos principais:

1. Informações de rastreamento:

   • Metadados que ajudam a explicar a origem do rastreamento, o status do rastreamento, informações sobre o tempo total de execução, etc.
   • Tags que fornecem contexto adicional para o rastreamento, como o usuário, a sessão e o código fornecido pelo desenvolvedor key pares. As tags podem ser usadas para pesquisar ou filtrar traços.
   • Avaliações que permitem que o senhor adicione um rótulo de feedback estruturado de seres humanos ou LLM juízes ou informações de verdade terrestre a um rastreamento ou a períodos específicos dentro de um rastreamento.

2. Dados de rastreamento:

   • A carga útil real, que contém os objetos Span instrumentados que capturam a execução passo a passo do seu aplicativo, da entrada à saída.

dica

Consulte a documentação do site API para obter mais informações sobre como converter ou extrair dados desses objetos de classe de dados.

1. Informações de rastreamento

O recurso de rastreamento do TraceInfo dentro do MLflow tem como objetivo fornecer um instantâneo leve de dados críticos sobre o rastreamento geral. TraceInfo é um objeto de classe de dados que contém metadados sobre o rastreamento.

Esses metadados incluem informações sobre a origem do rastreamento, o status e vários outros dados que ajudam a recuperar e filtrar rastreamentos quando usados com o site mlflow.client.MlflowClient.search_traces e para a navegação de rastreamentos na UI do site MLflow. Para saber mais sobre como os metadados TraceInfo são usados na pesquisa, veja exemplos aqui.

Parâmetro	Tipo de dados	Descrição
trace_id	str	O identificador primário do rastreamento.
trace_location	TraceLocation	O local em que o rastreamento é armazenado, representado como um objeto:py:class:~mlflow.entities.TraceLocation. Atualmente, o MLflow suporta o MLflow Experiment ou a Databricks Inference Table como local de rastreamento.
request_time	int	Tempo de início do rastreamento, em milissegundos.
state	TraceState	Estado do rastreamento, representado como um enum:py:class:~mlflow.entities.TraceState. Pode ser um dos [OK, ERROR, IN_PROGRESS, STATE_UNSPECIFIED].
request_preview	Optional[str]	Solicitação para o modelo/agente, equivalente à entrada da extensão raiz, mas codificada em JSON e pode ser truncada.
response_preview	Optional[str]	Resposta do modelo/agente, equivalente à saída da extensão raiz, mas codificada em JSON e pode ser truncada.
client_request_id	Optional[str]	ID de solicitação fornecida pelo cliente associada ao rastreamento. Isso pode ser usado para identificar o rastreamento/solicitação de um sistema externo que produziu o rastreamento, por exemplo, um ID de sessão em um aplicativo da web.
execution_duration	Optional[int]	duração do rastreamento, em milissegundos.
trace_metadata	dict[str, str]	valor-chave par associado ao rastreamento. Eles são projetados para valores imutáveis, como o ID de execução associado ao rastreamento.
tags	dict[str, str]	Tags associadas ao rastreamento. Eles são projetados para valores mutáveis, que podem ser atualizados depois que o rastreamento é criado por meio da UI ou API do MLflow.
assessments	list[Assessment]	Lista de avaliações associadas ao rastreamento.

Os dados contidos no objeto TraceInfo são usados para preencher a página de rastreamento view na UI de acompanhamento MLflow, conforme mostrado abaixo.

Os principais componentes dos objetos do MLflow TraceInfo estão listados abaixo.

Metadados

Avaliações

As avaliações são cruciais para avaliar a qualidade e a exatidão do comportamento de seu aplicativo GenAI, conforme capturado nos rastreamentos. Eles permitem que o senhor anexe rótulos estruturados, pontuações ou informações de verdade fundamental a um rastreamento ou a períodos específicos dentro de um rastreamento.

O MLflow define dois tipos principais de avaliações, ambos herdados de um conceito básico Assessment:

1. Feedback : Representa julgamentos qualitativos ou quantitativos sobre o resultado de uma operação. Isso pode vir de revisores humanos, do LLM como juiz ou de funções de pontuação personalizadas.
2. Expectativas : Representa a verdade básica ou o resultado esperado para uma determinada operação, geralmente usado para comparação direta com os resultados reais.

Normalmente, as avaliações são registradas em um rastreamento usando funções como mlflow.log_feedback(), mlflow.log_expectation(), ou a mais geral mlflow.log_assessment().

Fonte de avaliação

Cada avaliação é associada a uma fonte para rastrear sua origem.

• source_type : Uma enumeração mlflow.entities.AssessmentSourceType. Os valores-chave incluem:

  • HUMAN: Feedback ou expectativa fornecidos por um ser humano.
  • LLM_JUDGE: Avaliação gerada por um LLM atuando como juiz.
  • CODE: Avaliação gerada por uma regra programática, heurística ou pontuador personalizado.

• source_id : Um identificador de cadeias de caracteres para a fonte específica (por exemplo, ID do usuário, nome do modelo do juiz LLM, nome do script).

Python

from mlflow.entities import AssessmentSource, AssessmentSourceType

# Example: Human source
human_source = AssessmentSource(
    source_type=AssessmentSourceType.HUMAN,
    source_id="reviewer_alice@example.com"
)

# Example: LLM Judge source
llm_judge_source = AssessmentSource(
    source_type=AssessmentSourceType.LLM_JUDGE,
    source_id="gpt-4o-mini-evaluator"
)

# Example: Code-based scorer source
code_source = AssessmentSource(
    source_type=AssessmentSourceType.CODE,
    source_id="custom_metrics/flesch_kincaid_scorer.py"
)

Feedback

O feedback captura julgamentos sobre a qualidade ou as características de uma saída de traço ou amplitude.

Campos-chave :

Parâmetro	Tipo de dados	Descrição
name	str	O nome da avaliação. Se não for fornecido, será usado o nome default " feedback".
value	Optional[FeedbackValueType]	O valor do feedback. Pode ser um float, int, str, bool, uma lista desses tipos ou um dict com chave de strings e valores desses tipos.
error	Optional[Union[Exception, AssessmentError]]	Um erro opcional associado ao feedback. Isso é usado para indicar que o feedback não é válido ou não pode ser processado. Aceita um objeto de exceção, um objeto:py:class:~mlflow.entities.Exception ouAssessmentError.
rationale	Optional[str]	A justificativa/justificativa para o feedback.
source	Optional[AssessmentSource]	A fonte da avaliação. Se não for fornecida, a fonte default será CODE.
trace_id	Optional[str]	O ID do rastreamento associado à avaliação. Se não for definida, a avaliação ainda não está associada a nenhum rastreamento.
metadata	Optional[dict[str, str]]	Os metadados associados à avaliação.
span_id	Optional[str]	O ID do intervalo associado à avaliação, caso a avaliação deva ser associada a um intervalo específico no rastreamento.
create_time_ms	Optional[int]	O tempo de criação da avaliação em milissegundos. Se não for definido, a hora atual será usada.
last_update_time_ms	Optional[int]	A hora da última atualização da avaliação em milissegundos. Se não for definido, a hora atual será usada.

Exemplo :

Python

import mlflow
from mlflow.entities import Feedback, AssessmentSource, AssessmentSourceType

# Log simple binary feedback
mlflow.log_feedback(
    trace_id="trace_123",
    name="is_correct",
    value=True,
    source=AssessmentSource(source_type=AssessmentSourceType.HUMAN, source_id="user_bob"),
    rationale="The answer provided was factually accurate."
)

# Log a numeric score from an LLM judge
llm_judge_feedback = Feedback(
    name="relevance_score",
    value=0.85,
    source=AssessmentSource(source_type=AssessmentSourceType.LLM_JUDGE, source_id="claude-3-sonnet"),
    rationale="The response directly addressed the user's core question.",
    metadata={"judge_prompt_version": "v1.2"}
)
# Assuming trace_id is known, you can also use log_assessment
# mlflow.log_assessment(trace_id="trace_456", assessment=llm_judge_feedback)

Expectativa

As expectativas definem a verdade básica ou o resultado desejado para uma operação.

Campos-chave :

Parâmetro	Tipo de dados	Descrição
name	str	O nome da avaliação.
value	Any	O valor esperado das operações. Esse pode ser qualquer valor serializável em JSON.
source	Optional[AssessmentSource]	A fonte da avaliação. Se não for fornecida, a fonte default será HUMAN. (Consulte a Fonte de Avaliação para obter mais detalhes).
trace_id	Optional[str]	O ID do rastreamento associado à avaliação. Se não for definida, a avaliação ainda não está associada a nenhum rastreamento.
metadata	Optional[dict[str, str]]	Os metadados associados à avaliação.
span_id	Optional[str]	O ID do intervalo associado à avaliação, caso a avaliação deva ser associada a um intervalo específico no rastreamento.
create_time_ms	Optional[int]	O tempo de criação da avaliação em milissegundos. Se não for definido, a hora atual será usada.
last_update_time_ms	Optional[int]	A hora da última atualização da avaliação em milissegundos. Se não for definido, a hora atual será usada.

Exemplo :

Python

import mlflow
from mlflow.entities import Expectation, AssessmentSource, AssessmentSourceType

# Log a ground truth answer
mlflow.log_expectation(
    trace_id="trace_789",
    name="ground_truth_response",
    value="The Battle of Hastings was in 1066.",
    source=AssessmentSource(source_type=AssessmentSourceType.HUMAN, source_id="history_expert_01")
)

# Log an expected structured output for a tool call
expected_tool_output = Expectation(
    name="expected_tool_call_result",
    value={"result": {"status": "success", "data": "item_abc_123"}},
    metadata={"tool_name": "inventory_check"}
)
# Assuming trace_id is known:
# mlflow.log_assessment(trace_id="trace_101", assessment=expected_tool_output)

Erro de avaliação

Usado para log erros que ocorreram durante a geração ou o cálculo do feedback ou de uma expectativa (por exemplo, um juiz LLM falhou).

Campos-chave :

• error_code (str): Um código para o erro (por exemplo, " RATE_LIMIT_EXCEEDED ", " JUDGE_ERROR ").
• error_message (Opcional [str]): mensagem de erro detalhada.
• stack_trace (Opcional [str]): Stack trace, se disponível.

Exemplo :

Python

import mlflow
from mlflow.entities import AssessmentError, Feedback, AssessmentSource, AssessmentSourceType

judge_error = AssessmentError(
    error_code="LLM_JUDGE_TIMEOUT",
    error_message="The LLM judge timed out after 30 seconds while assessing relevance."
)

mlflow.log_feedback(
    trace_id="trace_error_example",
    name="relevance_with_judge_v2",
    source=AssessmentSource(source_type=AssessmentSourceType.LLM_JUDGE, source_id="custom_judge_model"),
    error=judge_error
    # Note: `value` is typically None when an error is provided
)

Essas entidades oferecem uma maneira flexível, porém estruturada, de associar dados qualitativos e quantitativos ricos aos seus traços, formando uma parte crucial dos recursos de observabilidade e avaliação no MLflow Tracing.

Etiquetas

A propriedade tags no objeto TraceInfo do MLflow é usada para fornecer contexto adicional para o rastreamento. Essas tags podem ser usadas para pesquisar, filtrar ou fornecer informações adicionais sobre o rastreamento.

As tags são par key-value e são mutáveis. Isso significa que o senhor pode adicionar, modificar ou remover tags a qualquer momento, mesmo depois de o rastreamento ter sido registrado em um experimento.

Para saber como adicionar tags personalizadas para capturar metadados view personalizados,acesse e clique em Attach custom tags / metadata.

Etiquetas padrão

MLflow Usa um conjunto de tags padrão para informações contextuais comuns sobre usuários, sessões e ambiente, que permitem recursos aprimorados de filtragem e agrupamento na interface do usuário MLflow e em SDK:

• mlflow.trace.session: tag padrão para ID de sessão, introduzida em Track Users & Sessions.
• mlflow.trace.user: tag padrão para ID de usuário, introduzida em Track Users & Sessions.
• mlflow.source.name: o ponto de entrada ou script que gerou o rastreamento.
• mlflow.source.git.commit: Se o senhor executar a partir de um repositório Git, o hash commit do código-fonte.
• mlflow.source.type: O tipo de fonte que gerou o rastreamento, geralmente PROJECT (para execução do projeto MLflow ) ou NOTEBOOK (se executado a partir de um Notebook).

O senhor pode saber mais sobre como implementá-los no guia para acompanhamento de usuários & sessions e acompanhamento de ambientes & context.

2. Dados de rastreamento

O objeto MLflow TraceData, acessível via Trace.data, contém a carga útil principal do rastreamento. Ele contém principalmente a sequência de operações (spans) que ocorreram, juntamente com a solicitação inicial que acionou o rastreamento e a resposta final produzida.

Campos-chave :

• spans (Lista [Span]):

  • Esta é uma lista de objetos Span (em conformidade com as especificações mlflow.entities.Span e OpenTelemetry) que representam as etapas individuais, as operações ou as chamadas de função dentro do rastreamento. Cada período detalha uma unidade específica de trabalho.
  • As extensões são organizadas hierarquicamente por meio de parent_id para representar o fluxo de execução.
  • Consulte a seção Span Schema abaixo para obter uma análise detalhada de um objeto Span.

nota

As propriedades request e response são preservadas para fins de compatibilidade com versões anteriores. Seus valores são consultados nos respectivos atributos inputs e outputs da extensão raiz e não são definidos diretamente pelo usuário no objeto TraceData.

• request (rua):

  • Uma cadeia de caracteres serializada JSONque representa os dados de entrada para o intervalo raiz do rastreamento. Normalmente, essa é a solicitação do usuário final ou os parâmetros iniciais que invocaram o aplicativo ou o fluxo de trabalho rastreado.
  • Exemplo : '{"query": "What is MLflow Tracing?", "user_id": "user123"}'

• response (rua):

  • A JSON- strings serializadas que representam os dados de saída finais do intervalo raiz do aplicativo rastreado ou fluxo de trabalho.
  • Exemplo : '{"answer": "MLflow Tracing provides observability...", "confidence": 0.95}'

Representação conceitual :

Embora você normalmente interaja com TraceData por meio de um objeto mlflow.entities.Trace recuperado por meio do cliente (por exemplo, client.get_trace(trace_id).data), conceitualmente, ele agrupa esses componentes principais:

Python

# Conceptual structure (not direct instantiation like this)
class TraceData:
    def __init__(self, spans: list[Span], request: str, response: str):
        self.spans = spans # List of Span objects
        self.request = request # JSON string: Overall input to the trace
        self.response = response # JSON string: Overall output of the trace

Compreender o site TraceData é key para analisar programaticamente o caminho de execução detalhado e as transformações de dados que ocorrem em todo o ciclo de vida do aplicativo GenAI.

Vãos

O objeto Span no recurso de rastreamento do site MLflow fornece informações detalhadas sobre as etapas individuais do rastreamento.

Ele está em conformidade com a especificação OpenTelemetry Span. Cada objeto Span contém informações sobre a etapa que está sendo instrumentada, incluindo span_id, nome, start_time, parent_id, status, entradas, saídas, atributos e eventos.

Esquema de expansão

As extensões são o núcleo dos dados de rastreamento. Eles registram key, dados críticos sobre cada uma das etapas do seu aplicativo genai.

Ao acessar view seus traços na interface do usuário MLflow, o senhor visualiza uma coleção de períodos, conforme mostrado abaixo.

As seções abaixo fornecem um view detalhado da estrutura de um vão.

Tipos de extensão

Os tipos de extensão são uma forma de categorizar extensões em um rastreamento. Por default, o tipo de extensão é definido como "UNKNOWN" ao usar o decorador de rastreamento. O MLflow fornece um conjunto de tipos de intervalos predefinidos para casos de uso comuns, além de permitir que o usuário defina tipos de intervalos personalizados.

Os seguintes tipos de extensão estão disponíveis. Além disso, você pode definir o tipo de extensão para qualquer valor str especificado pelo desenvolvedor.

Tipo de extensão	Descrição
"CHAT_MODEL"	Representa uma consulta a um modelo de bate-papo. Esse é um caso especial de uma interação LLM.
"CHAIN"	Representa uma cadeia de operações.
"AGENT"	Representa as operações de um agente autônomo.
"TOOL"	Representa a execução de uma ferramenta (normalmente por um agente), como consultar um mecanismo de pesquisa.
"EMBEDDING"	Representa uma operação de incorporação de texto.
"RETRIEVER"	Representa uma operação de recuperação de contexto, como a consulta a um banco de dados de vetores.
"PARSER"	Representa uma operação de análise, transformando o texto em um formato estruturado.
"RERANKER"	Representa uma operação de reclassificação, ordenando os contextos recuperados com base na relevância.
"UNKNOWN"	Um tipo de vão default que é usado quando nenhum outro tipo de vão é especificado.

Para definir um tipo de extensão, você pode passar o parâmetro span_type para o decorador mlflow.trace ou o gerenciador de contexto mlflow.start_span. Quando o senhor estiver usando o rastreamento automático, o tipo de extensão é definido automaticamente pelo MLflow.

Python

import mlflow
from mlflow.entities import SpanType


# Using a built-in span type
@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_documents(query: str):
    ...


# Setting a custom span type
with mlflow.start_span(name="add", span_type="MATH") as span:
    span.set_inputs({"x": z, "y": y})
    z = x + y
    span.set_outputs({"z": z})

    print(span.span_type)
    # Output: MATH

Esquema para tipos específicos de extensão

MLflow tem um conjunto de tipos predefinidos de intervalos (consulte mlflow.entities.SpanType), e determinados tipos de intervalos têm propriedades necessárias para habilitar funcionalidades adicionais na interface do usuário e na tarefa posterior, como a avaliação.

Expansões de retriever

O tipo de extensão RETRIEVER é usado para operações que envolvem a recuperação de dados de um armazenamento de dados (por exemplo, consulta a documentos de um armazenamento de vetores). Espera-se que a saída de um intervalo RETRIEVER seja uma lista de documentos.

Cada documento da lista deve ser um dicionário (ou um objeto que possa ser serializado em um dicionário com a seguinte chave) e, idealmente, inclui:

• page_content (str): O conteúdo de texto do pedaço de documento recuperado.

• metadata (Optional[Dict[str, Any]]): Um dicionário de metadados adicionais associados ao documento.

  • MLflow A interface do usuário e as métricas de avaliação podem procurar especificamente por doc_uri (um URI de strings para a origem do documento) e chunk_id (um identificador de strings se o documento fizer parte de um documento maior em pedaços) dentro desses metadados para aprimorar a exibição e a funcionalidade.

• id (Optional[str]): Um identificador exclusivo opcional para o próprio fragmento do documento.

Exemplo de um Retriever Span em ação :

Python

import mlflow
from mlflow.entities import SpanType, Document


def search_store(query: str) -> list[(str, str)]:
    # Simulate retrieving documents (e.g., from a vector database)
    return [
        ("MLflow Tracing helps debug GenAI applications...", "docs/mlflow/tracing_intro.md"),
        ("Key components of a trace include spans...", "docs/mlflow/tracing_datamodel.md"),
        ("MLflow provides automatic instrumentation...", "docs/mlflow/auto_trace.md")
    ]


@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_relevant_documents(query: str):
    # Get documents from the search store
    docs = search_store(query)

    # Get the current active span (created by @mlflow.trace)
    span = mlflow.get_current_active_span()

    # Set the outputs of the span in accordance with the tracing schema
    outputs = [Document(page_content=doc, metadata={"doc_uri": uri}) for doc, uri in docs]
    span.set_outputs(outputs)

    # Return the original format for downstream usage
    return docs


# Example usage
user_query = "MLflow Tracing benefits"
retrieved_docs = retrieve_relevant_documents(user_query)

# Read path: Reconstructing the document list from the span outputs
trace_id = mlflow.get_last_active_trace_id()
trace = mlflow.get_trace(trace_id)
span = trace.search_spans(name="retrieve_relevant_documents")[0]
documents = [Document(**doc) for doc in span.outputs]

print(documents)

A conformidade com essa estrutura, especialmente a inclusão de page_content e de metadata relevantes, como doc_uri, garantirá que os intervalos de RETRIEVER sejam renderizados de forma informativa na interface do usuário de MLflow (por exemplo, exibindo o conteúdo do documento e fornecendo links) e que a tarefa de avaliação downstream possa processar corretamente o contexto recuperado.

Conclusão de bate-papo & Tool Call Spanes

Os intervalos do tipo CHAT_MODEL ou LLM são usados para representar interações com uma API de conclusões de bate-papo (por exemplo, as conclusões de bate-papo da OpenAI, ou a API de mensagens da Anthropic). Esses intervalos também podem capturar informações sobre ferramentas (funções) disponibilizadas ou usadas pelo modelo.

Como os provedores podem ter esquemas diferentes para sua API, não há restrições rigorosas quanto ao formato das entradas e saídas do intervalo para a própria chamada LLM bruta. No entanto, para permitir o recurso de UI avançada (como exibição de conversas e visualização de chamadas de ferramentas) e padronizar os dados para avaliação, o site MLflow define atributos específicos para mensagens de bate-papo e definições de ferramentas.

Consulte o exemplo abaixo para obter uma demonstração rápida de como usar as funções de utilidades descritas acima, bem como como recuperá-las usando a função span.get_attribute():

Python

import mlflow
from mlflow.entities.span import SpanType # Corrected from mlflow.entities.span import SpanType
from mlflow.tracing.constant import SpanAttributeKey
from mlflow.tracing import set_span_chat_messages, set_span_chat_tools

# example messages and tools
messages = [
    {
        "role": "system",
        "content": "please use the provided tool to answer the user's questions",
    },
    {"role": "user", "content": "what is 1 + 1?"},
]

tools = [
    {
        "type": "function",
        "function": {
            "name": "add",
            "description": "Add two numbers",
            "parameters": {
                "type": "object",
                "properties": {
                    "a": {"type": "number"},
                    "b": {"type": "number"},
                },
                "required": ["a", "b"],
            },
        },
    }
]


@mlflow.trace(span_type=SpanType.CHAT_MODEL)
def call_chat_model(messages, tools):
    # mocking a response
    response = {
        "role": "assistant",
        "tool_calls": [
            {
                "id": "123",
                "function": {"arguments": '{"a": 1,"b": 2}', "name": "add"},
                "type": "function",
            }
        ],
    }

    combined_messages = messages + [response]

    span = mlflow.get_current_active_span()
    set_span_chat_messages(span, combined_messages)
    set_span_chat_tools(span, tools)

    return response


call_chat_model(messages, tools)

trace = mlflow.get_last_active_trace()
span = trace.data.spans[0]

print("Messages: ", span.get_attribute(SpanAttributeKey.CHAT_MESSAGES))
print("Tools: ", span.get_attribute(SpanAttributeKey.CHAT_TOOLS))

Próximas etapas

Continue sua jornada com estas ações recomendadas e o tutorial.

• Instrumente seu aplicativo com rastreamento - aplique esses conceitos de modelo de dados para adicionar rastreamento ao seu aplicativo
• Consultar traços via SDK - Use o modelo de dados para analisar traços de forma programática
• Anexar tags / metadados personalizados - Enriquecer os traços com informações contextuais

Guia de referência

Explore a documentação detalhada sobre conceitos relacionados.

• Conceitos de rastreamento - Entenda os conceitos de alto nível por trás do modelo de dados
• Avaliações de registro - Saiba como anexar feedback e expectativas aos rastreamentos
• Excluir rastros - gerenciar o ciclo de vida e a limpeza dos rastros