Поделиться через

Основные понятия диапазона

Объект Span является основным стандартным блоком в модели данных Trace. Он служит контейнером для получения сведений о отдельных шагах трассировки, таких как вызовы LLM, выполнение инструментов, операции извлечения и многое другое.

Диапазоны упорядочены иерархически в трассировке для представления потока выполнения приложения. Каждый диапазон фиксирует:

  • Входные и выходные данные
  • Сведения о времени (время начала и окончания)
  • Состояние (успех или ошибка)
  • Метаданные и атрибуты операции
  • Отношения с другими диапазонами (связи родитель-дочерний)

Архитектура диапазона

Схема объекта Span

Проектирование диапазона MLflow поддерживает совместимость с спецификациями OpenTelemetry. Схема включает в себя одиннадцать основных свойств:

Недвижимость Тип Description
span_id str Уникальный идентификатор этого сегмента в трассировке
trace_id str Ссылки соединяются с родительской трассировкой
parent_id Optional[str] Устанавливает иерархическую связь; None для корневых спанов
name str Определяемое пользователем или автоматически созданное имя диапазона
start_time_ns int Метка времени Unix (наносекунды), когда начался промежуток
end_time_ns int Метка времени Unix (наносекунды) при завершении периода
status SpanStatus Состояние диапазона: OK, UNSETили ERROR с необязательным описанием
inputs Optional[Any] Входные данные, введенные в эту операцию
outputs Optional[Any] Выходные данные, выходя из этой операции
attributes Dict[str, Any] Пары "Ключ-значение метаданных", предоставляющие аналитические сведения о поведении
events List[SpanEvent] Исключения на уровне системы и сведения о трассировке стека

Полные сведения см. в справочнике по API MLflow.

Атрибуты диапазона

Атрибуты — это пары "ключ-значение", которые предоставляют представление о изменениях поведения для вызовов функций и методов. Они записывают метаданные о конфигурации и контексте выполнения операции.

Вы можете добавлять такие атрибуты, как сведения каталога Unity, сведения о конечной точке обслуживания модели и метаданные инфраструктуры для повышения обсервабельности.

set_attributes() Пример для вызова LLM:

span.set_attributes({
    "ai.model.name": "claude-3-5-sonnet-20250122",
    "ai.model.version": "2025-01-22",
    "ai.model.provider": "anthropic",
    "ai.model.temperature": 0.7,
    "ai.model.max_tokens": 1000,
})

Типы диапазонов

MLflow предоставляет предопределенные SpanType значения для классификации. Можно также использовать пользовательские строковые значения для специализированных операций.

Тип Description
CHAT_MODEL Запрос к модели чата (специализированное взаимодействие LLM)
CHAIN Цепочка операций
AGENT Операция автономного агента
TOOL Выполнение операций (обычно агентами), таких как поисковые запросы
EMBEDDING Операция внедрения текста
RETRIEVER Операция извлечения контекста, например запросы к векторной базе данных
PARSER Анализ операции преобразования текста в структурированный формат
RERANKER Повторное ранжирование контекстов упорядочения операций по релевантности
MEMORY Операция сохранения контекста в долгосрочной памяти
UNKNOWN Тип по умолчанию, если другой тип не указан

Настройка типов диапазонов

Используйте параметр span_type с декораторами или управляющими контекстом для установки SpanType:

import mlflow
from mlflow.entities import SpanType

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

# Using a custom span type
@mlflow.trace(span_type="ROUTER")
def route_request(request):
    ...

# With context manager
with mlflow.start_span(name="process", span_type=SpanType.TOOL) as span:
    span.set_inputs({"data": data})
    result = process_data(data)
    span.set_outputs({"result": result})

Поиск диапазонов по типу

Запросы осуществляются программным способом с помощью MLflow search_spans().

import mlflow
from mlflow.entities import SpanType

trace = mlflow.get_trace("<trace_id>")
retriever_spans = trace.search_spans(span_type=SpanType.RETRIEVER)

При просмотре трассировок можно также фильтровать по типу диапазона в пользовательском интерфейсе MLflow.

Активные и завершенные интервалы

Активный диапазон или LiveSpan записывается, например, в функции, декорированной с помощью @mlflow.trace или контекстным менеджером диапазона. После выхода из декорированной функции или диспетчера контекста, интервал завершается и становится неизменяемым Span.

Чтобы изменить активный диапазон, получите дескриптор диапазона, используя mlflow.get_current_active_span().

RETRIEVER схема диапазона

RETRIEVER Тип диапазона обрабатывает операции, связанные с получением данных из хранилища данных, например запросом документов из векторного хранилища. Этот тип диапазона имеет определенную выходную схему, которая обеспечивает расширенные функции пользовательского интерфейса и возможности оценки. Выходные данные должны быть списком документов, где каждый документ является словарем с:

  • page_content (str): Текстовое содержимое полученного фрагмента документа
  • metadata (Optional[Dict[str, Any]]): Дополнительные метаданные, в том числе:
    • doc_uri (str): URI источника документа. При использовании Vector Search в Databricks диапазоны RETRIEVER могут включать пути томов Unity Catalog в doc_uri метаданных для полного отслеживания происхождения.
    • chunk_id (str): Идентификатор, если документ является частью более крупного фрагментированного документа
  • id (Optional[str]): Уникальный идентификатор блока документа

Сущность MLflow Document помогает создать эту выходную структуру.

Пример реализации:

import mlflow
from mlflow.entities import SpanType, Document

def search_store(query: str) -> list[tuple[str, str]]:
    # Simulate retrieving documents 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):
    docs = search_store(query)
    span = mlflow.get_current_active_span()

    # Set outputs in the expected format
    outputs = [
        Document(page_content=doc, metadata={"doc_uri": uri})
        for doc, uri in docs
    ]
    span.set_outputs(outputs)

    return docs

# Usage
user_query = "MLflow Tracing benefits"
retrieved_docs = retrieve_relevant_documents(user_query)

Дальнейшие шаги

  • Last updated on