RagaAI Catalyst 项目中的追踪管理(Trace Management)技术解析

RagaAI Catalyst 项目中的追踪管理(Trace Management)技术解析

RagaAI-Catalyst Python SDK for Agent AI Observability, Monitoring and Evaluation Framework. Includes features like agent, llm and tools tracing, debugging multi-agentic system, self-hosted dashboard and advanced analytics with timeline and execution graph view 项目地址: https://gitcode.com/gh_mirrors/ra/RagaAI-Catalyst

概述

在现代AI应用开发中，如何有效地追踪、记录和分析模型运行过程中的各种信息是一个关键挑战。RagaAI Catalyst项目提供的追踪管理(Trace Management)功能为开发者提供了一套完整的解决方案，特别是在LangChain和LlamaIndex等流行框架中的应用场景中表现尤为出色。

追踪管理核心功能

RagaAI Catalyst的追踪管理系统主要提供以下核心能力：

1. 全流程追踪：记录AI模型从输入到输出的完整处理过程
2. 上下文管理：灵活添加和关联处理过程中的上下文信息
3. 数据集管理：动态扩展数据集结构和内容
4. 评估体系：内置多种评估指标对模型表现进行量化分析

初始化追踪组件

LangChain场景下的初始化

from ragaai_catalyst import Tracer
tracer_dataset_name = "tracer_dataset_name"

tracer = Tracer(
    project_name=project_name,
    dataset_name=tracer_dataset_name,
    metadata={"key1": "value1", "key2": "value2"},
    tracer_type="langchain",
    pipeline={
        "llm_model": "gpt-4o-mini",
        "vector_store": "faiss",
        "embed_model": "text-embedding-ada-002",
    }
)

关键参数说明：

• project_name: 项目标识，用于区分不同项目的数据
• dataset_name: 数据集名称，同一项目下可包含多个数据集
• metadata: 可选的元数据字典，用于记录额外信息
• tracer_type: 指定追踪组件类型，支持"langchain"和"llamaindex"
• pipeline: 描述处理管道的配置信息

LlamaIndex场景下的初始化

LlamaIndex场景下的初始化与LangChain类似，主要区别在于tracer_type参数：

tracer = Tracer(
    project_name=project_name,
    dataset_name=tracer_dataset_name,
    metadata={"key1": "value1", "key2": "value2"},
    tracer_type="llamaindex",
    pipeline={
        "llm_model": "gpt-4o-mini",
        "vector_store": "faiss",
        "embed_model": "text-embedding-ada-002",
    }
)

使用追踪组件记录处理过程

LangChain示例

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
chat = ChatLiteLLM(model="gpt-4o-mini")

messages = [
    HumanMessage(
        content="Translate this sentence from English to German. I love you."
    )
]
with tracer:
    response = chat(messages)

LlamaIndex示例

with tracer:
  for question in questions:
    response = process_document(source_doc_path, None, question)
    print(f"Question: {question}\nResponse: {response}\n")

with tracer:语句块会自动记录所有在该上下文中执行的操作，包括模型调用、数据处理等关键信息。

添加上下文信息

在实际应用中，往往需要为追踪记录添加额外的上下文信息：

with tracer:
    response = chat(messages)
    tracer.add_context("用户ID:12345 会话ID:67890")

上下文信息可以是任何有助于理解处理过程的字符串，如用户标识、会话ID、时间戳等。

数据集管理

添加数据行

from ragaai_catalyst import Dataset
dataset_manager = Dataset(project_name=project_name)
add_rows_csv_path = "path_to_dataset.csv"
dataset_manager.add_rows(csv_path=add_rows_csv_path, dataset_name=dataset_name)

添加数据列

text_fields = [
    {
        "role": "system",
        "content": "you are an evaluator, which answers only in yes or no."
    },
    {
        "role": "user",
        "content": "are any of the {{asdf}} {{abcd}} related to broken hand"
    }
]
column_name = "from_colab_v1"
provider = "openai"
model = "gpt-4o-mini"

variables={
    "asdf": "context",
    "abcd": "feedback"
}

dataset_manager.add_columns(
    text_fields=text_fields,
    dataset_name=dataset_name,
    column_name=column_name,
    provider=provider,
    model=model,
    variables=variables
)

评估指标管理

RagaAI Catalyst提供了强大的评估功能，支持多种评估指标：

from ragaai_catalyst import Evaluation
evaluation = Evaluation(project_name=project_name,
                       dataset_name=tracer_dataset_name)

schema_mapping={
    'prompt': 'prompt',
    'response': 'response',
    'context': 'context',
}

metrics = [
    {"name": "Faithfulness", "config": {"model": "gpt-4o-mini", "provider": "openai", "threshold": {"gte": 0.323}}, "column_name": "Faithfulness_v1_gte", "schema_mapping": schema_mapping},
    {"name": "Hallucination", "config": {"model": "gpt-4o-mini", "provider": "openai", "threshold": {"lte": 0.323}}, "column_name": "Hallucination_v1_lte", "schema_mapping": schema_mapping},
    {"name": "Context Relevancy", "config": {"model": "gemini-1.5-flash", "provider": "gemini", "threshold": {"eq": 0.323}}, "column_name": "Context_Relevancy_v1_eq", "schema_mapping": schema_mapping},
]

evaluation.add_metrics(metrics=metrics)
evaluation.get_status()

增量评估

当数据集新增数据时，可以仅对新数据进行评估：

evaluation.append_metrics(display_name="Faithfulness_v1")

最佳实践建议

1. 合理设计元数据：在初始化追踪组件时，提供有意义的元数据，便于后续分析
2. 上下文粒度控制：添加上下文时保持适当的信息粒度，既不过于详细也不过于简略
3. 评估指标选择：根据实际应用场景选择合适的评估指标组合
4. 增量评估策略：对于频繁更新的数据集，采用增量评估策略提高效率
5. 数据集版本管理：通过不同的dataset_name实现数据集版本管理

总结

RagaAI Catalyst的追踪管理系统为AI应用开发提供了全面的追踪、记录和评估能力。通过本文介绍的核心功能和使用方法，开发者可以更好地理解和利用这一强大工具，提升AI应用的开发效率和质量控制水平。无论是LangChain还是LlamaIndex框架，都能无缝集成，为复杂的AI处理流程提供清晰的追踪记录和客观的评估结果。

RagaAI-Catalyst Python SDK for Agent AI Observability, Monitoring and Evaluation Framework. Includes features like agent, llm and tools tracing, debugging multi-agentic system, self-hosted dashboard and advanced analytics with timeline and execution graph view 项目地址: https://gitcode.com/gh_mirrors/ra/RagaAI-Catalyst