概述

RagaAI Catalyst 是一个企业级 MLOps 和 LLM 应用监控平台，提供完整的模型生命周期管理能力。该平台支持项目创建、数据集管理、应用追踪、提示词管理、合成数据生成、护栏管理和红队测试等核心功能。资料来源：README.md:1-15

本页面将指导用户完成 RagaAI Catalyst SDK 的完整安装流程、认证配置以及基础使用示例，帮助开发者快速上手使用该平台进行 LLM 应用的开发与监控。

概述

RagaAI Catalyst 的配置与认证系统是整个平台的基础模块，负责管理用户身份验证、凭证存储以及与后端服务的安全通信。所有使用 RagaAI Catalyst 功能之前必须完成正确的配置和身份认证。

核心认证流程通过 RagaAICatalyst 类实现，该类封装了所有与平台服务的交互逻辑，支持通过环境变量或直接传入参数两种方式进行配置。

认证凭证获取

获取步骤

1. 登录 RagaAI Catalyst 账户
2. 进入 Profile Settings → Authentication 页面
3. 点击 Generate New Key 生成新的访问密钥

认证成功后，用户将获得以下凭证信息：

SDK 初始化配置

基本初始化

使用 RagaAICatalyst 类进行 SDK 初始化是最基础的配置方式：

from ragaai_catalyst import RagaAICatalyst

catalyst = RagaAICatalyst(
    access_key="YOUR_ACCESS_KEY",      # 用户访问密钥
    secret_key="YOUR_SECRET_KEY",      # 用户密钥
    base_url="BASE_URL"                # 服务端点
)

环境变量配置

在生产环境中，推荐使用环境变量存储敏感凭证，避免硬编码：

import os
from dotenv import load_dotenv
from ragaai_catalyst import RagaAICatalyst

# 加载 .env 文件中的环境变量
load_dotenv()

catalyst = RagaAICatalyst(
    access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),
    secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),
    base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')
)

典型 .env 文件配置：

RAGAAI_CATALYST_ACCESS_KEY=your_access_key_here
RAGAAI_CATALYST_SECRET_KEY=your_secret_key_here
RAGAAI_CATALYST_BASE_URL=https://api.raga.ai/catalyst

追踪功能配置

Tracer 初始化

追踪系统需要单独配置 Tracer 类，与主 SDK 配合使用：

from ragaai_catalyst import RagaAICatalyst, init_tracing
from ragaai_catalyst.tracers import Tracer

# 1. 初始化主 SDK
catalyst = RagaAICatalyst(
    access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),
    secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),
    base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')
)

# 2. 初始化追踪器
tracer = Tracer(
    project_name=os.getenv('RAGAAI_PROJECT_NAME'),
    dataset_name=os.getenv('RAGAAI_DATASET_NAME'),
    tracer_type="agentic/langgraph"  # 支持多种追踪类型
)

# 3. 启用自动追踪
init_tracing(catalyst=catalyst, tracer=tracer)

Tracer 配置参数

自动仪表化配置

可通过 auto_instrumentation 参数控制各组件的自动追踪：

tracer = Tracer(
    project_name="Project_Name",
    dataset_name="Dataset_Name",
    tracer_type="agentic/langgraph",
    auto_instrumentation={
        'llm': True,           # LLM 调用追踪
        'tool': True,          # 工具调用追踪
        'agent': True,         # Agent 追踪
        'user_interaction': True,  # 用户交互追踪
        'file_io': True,       # 文件操作追踪
        'network': True,       # 网络请求追踪
        'custom': True         # 自定义事件追踪
    }
)

支持的追踪器类型

RagaAI Catalyst 支持多种框架的追踪集成：

配置架构

graph TD
    A[应用程序] --> B[环境变量 / .env]
    B --> C[RagaAICatalyst 初始化]
    C --> D[认证服务验证]
    D --> E{验证结果}
    E -->|成功| F[创建项目 / 管理数据集]
    E -->|失败| G[认证错误]
    F --> H[Tracer 初始化]
    H --> I[init_tracing 启用追踪]
    I --> J[追踪数据上传]
    
    K[手动配置] --> C
    style G fill:#ffcccc

典型配置流程

sequenceDiagram
    participant User as 用户
    participant App as 应用程序
    participant Env as 环境变量
    participant SDK as RagaAICatalyst
    participant API as RagaAI API
    
    User->>API: 1. 生成认证密钥
    API->>User: 返回 access_key, secret_key
    User->>Env: 2. 配置环境变量
    App->>Env: 3. 加载环境变量
    App->>SDK: 4. 初始化 SDK
    SDK->>API: 5. 验证凭证
    API-->>SDK: 验证成功
    SDK-->>App: SDK 实例就绪
    App->>SDK: 6. 创建 Tracer
    SDK->>API: 7. 注册追踪器
    App->>SDK: 8. 调用 init_tracing
    SDK->>API: 9. 启用数据采集

项目级配置

除了全局 SDK 配置外，RagaAI Catalyst 还支持项目级别的配置管理：

# 创建项目时指定用例类型
project = catalyst.create_project(
    project_name="My-RAG-App",
    usecase="Q/A"  # 可选值: Chatbot, Q/A, Others, Agentic Application
)

# 查看可用的用例类型
print(catalyst.project_use_cases())

# 列出所有项目
projects = catalyst.list_projects()

数据集配置

数据集管理同样需要正确的项目配置：

from ragaai_catalyst import Dataset

dataset_manager = Dataset(project_name="Project_Name")

# 从 CSV 创建数据集
dataset_manager.create_from_csv(
    csv_path="path/to/your.csv",
    dataset_name="MyDataset",
    schema_mapping={
        'column1': 'schema_element1',
        'column2': 'schema_element2'
    }
)

安全建议

常见错误处理

认证配置过程中可能遇到的常见错误：

完整示例

以下是一个完整的配置与认证示例：

import os
from dotenv import load_dotenv
from ragaai_catalyst import RagaAICatalyst, init_tracing
from ragaai_catalyst.tracers import Tracer

# 加载环境变量
load_dotenv()

# 初始化主 SDK
catalyst = RagaAICatalyst(
    access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),
    secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),
    base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')
)

# 创建追踪器
tracer = Tracer(
    project_name=os.getenv('RAGAAI_PROJECT_NAME'),
    dataset_name=os.getenv('RAGAAI_DATASET_NAME'),
    tracer_type="agentic/langgraph"
)

# 启用追踪
init_tracing(catalyst=catalyst, tracer=tracer)

# 创建项目
project = catalyst.create_project(
    project_name="Test-Project",
    usecase="Agentic Application"
)

相关文档

• 快速开始指南 - 完整的快速入门教程
• 追踪管理 - 详细的追踪功能说明
• 评估框架 - 评估功能配置
• 项目与数据集管理 - 项目和数据集操作

概述

项目管理是 RagaAI Catalyst 平台的核心功能模块，用于组织和管理 AI 应用的全生命周期。通过项目管理功能，用户可以创建不同类型的 AI 应用项目、管理相关数据集、配置追踪器、运行评估任务以及执行红队测试。

RagaAI Catalyst 的项目管理采用分层架构设计，核心入口为 RagaAICatalyst 类，通过该类可以访问所有项目管理相关功能。资料来源：README.md

核心架构

整体架构图

graph TD
    A[用户应用] --> B[RagaAICatalyst 客户端]
    B --> C[项目管理]
    B --> D[数据集管理]
    B --> E[追踪管理]
    B --> F[评估管理]
    B --> G[提示词管理]
    B --> H[红队测试]
    
    C --> I[创建项目]
    C --> J[列举项目]
    C --> K[使用案例配置]
    
    D --> L[CSV 上传]
    D --> M[DataFrame 上传]
    D --> N[JSONL 上传]
    
    E --> O[LangGraph 追踪]
    E --> P[LangChain 追踪]
    E --> Q[其他框架追踪]

客户端初始化流程

sequenceDiagram
    participant User as 用户
    participant Env as 环境变量
    participant Catalyst as RagaAICatalyst
    
    User->>Env: 设置认证凭证
    User->>Catalyst: 初始化客户端
    Catalyst->>Catalyst: 验证凭证
    Catalyst-->>User: 返回客户端实例

客户端初始化

基本配置

使用 RagaAI Catalyst 之前，必须先初始化 RagaAICatalyst 客户端实例。客户端支持通过环境变量或直接传入参数两种方式进行配置。资料来源：README.md:1-30

from ragaai_catalyst import RagaAICatalyst

catalyst = RagaAICatalyst(
    access_key="YOUR_ACCESS_KEY",
    secret_key="YOUR_SECRET_KEY",
    base_url="BASE_URL"
)

环境变量配置方式

在实际项目中，推荐使用环境变量方式配置认证信息，便于管理敏感凭证。资料来源：examples/custom_agents/travel_agent/config.py:1-20

import os
from dotenv import load_dotenv
from ragaai_catalyst import RagaAICatalyst

load_dotenv()

catalyst = RagaAICatalyst(
    access_key=os.getenv("RAGAAI_CATALYST_ACCESS_KEY"),
    secret_key=os.getenv("RAGAAI_CATALYST_SECRET_KEY"),
    base_url=os.getenv("RAGAAI_CATALYST_BASE_URL"),
)

初始化参数说明

获取认证密钥

1. 登录 RagaAI Catalyst 平台 (https://catalyst.raga.ai/)
2. 进入个人资料设置 (Profile Settings)
3. 选择身份验证 (Authentication) 选项卡
4. 点击生成新密钥 (Generate New Key) 创建访问密钥和秘密密钥

资料来源：quickstart.md

项目创建与管理

创建新项目

使用 create_project 方法创建新项目，需要指定项目名称和用例类型。资料来源：README.md:35-50

# 创建新项目
project = catalyst.create_project(
    project_name="Test-RAG-App-1",
    usecase="Chatbot"  # 用例类型
)

# 获取可用用例列表
print(catalyst.project_use_cases())

支持的用例类型

列举项目

# 列出所有项目
projects = catalyst.list_projects()
print(projects)

追踪器与项目集成

项目管理与追踪系统紧密集成，每个项目可以配置专属的追踪器用于监控应用行为。资料来源：examples/crewai/scifi_writer/scifi_writer.py:1-25

追踪器初始化

from ragaai_catalyst import RagaAICatalyst, init_tracing
from ragaai_catalyst.tracers import Tracer

# 初始化 Catalyst 客户端
catalyst = RagaAICatalyst(
    access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'), 
    secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'), 
    base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')
)

# 创建项目级追踪器
tracer = Tracer(
    project_name=os.getenv('RAGAAI_PROJECT_NAME'),
    dataset_name=os.getenv('RAGAAI_DATASET_NAME'),
    tracer_type="agentic/crewai",
)

# 启用追踪
init_tracing(catalyst=catalyst, tracer=tracer)

追踪器类型对照表

资料来源：examples/langgraph/personal_research_assistant/research_assistant.py:1-30

完整配置示例

import os
from dotenv import load_dotenv
from ragaai_catalyst import RagaAICatalyst, init_tracing
from ragaai_catalyst.tracers import Tracer

load_dotenv()

def initialize_tracing():
    """初始化追踪配置"""
    catalyst = RagaAICatalyst(
        access_key=os.getenv("RAGAAI_CATALYST_ACCESS_KEY"),
        secret_key=os.getenv("RAGAAI_CATALYST_SECRET_KEY"),
        base_url=os.getenv("RAGAAI_CATALYST_BASE_URL"),
    )

    tracer = Tracer(
        project_name=os.getenv("RAGAAI_PROJECT_NAME"),
        dataset_name=os.getenv("RAGAAI_DATASET_NAME"),
        tracer_type="Agentic",
    )

    init_tracing(catalyst=catalyst, tracer=tracer)
    return tracer

项目相关组件

组件关系图

graph LR
    A[项目 Project] --> B[数据集 Dataset]
    A --> C[追踪器 Tracer]
    A --> D[评估 Evaluation]
    A --> E[提示词 Prompt]
    A --> F[红队测试]
    
    B --> B1[Schema Mapping]
    B --> B2[数据源]
    
    C --> C1[追踪数据]
    C --> C2[执行记录]
    
    D --> D1[评估指标]
    D --> D2[评估结果]

各组件功能说明

环境变量配置

必需环境变量

.env 文件配置示例

RAGAAI_CATALYST_ACCESS_KEY=your_access_key_here
RAGAAI_CATALYST_SECRET_KEY=your_secret_key_here
RAGAAI_CATALYST_BASE_URL=https://api.catalyst.raga.ai
RAGAAI_PROJECT_NAME=Test-Project
RAGAAI_DATASET_NAME=Test-Dataset

典型使用流程

完整项目生命周期流程

graph TD
    A[初始化客户端] --> B[创建项目]
    B --> C[配置用例类型]
    C --> D[创建数据集]
    D --> E[初始化追踪器]
    E --> F[开发应用代码]
    F --> G[运行评估]
    G --> H{评估结果}
    H -->|通过| I[部署上线]
    H -->|失败| J[问题修复]
    J --> F

分步操作示例

步骤 1: 初始化和认证

from ragaai_catalyst import RagaAICatalyst
import os
from dotenv import load_dotenv

load_dotenv()

catalyst = RagaAICatalyst(
    access_key=os.getenv("RAGAAI_CATALYST_ACCESS_KEY"),
    secret_key=os.getenv("RAGAAI_CATALYST_SECRET_KEY"),
    base_url=os.getenv("RAGAAI_CATALYST_BASE_URL"),
)

步骤 2: 创建和管理项目

# 创建新项目
project = catalyst.create_project(
    project_name="My-RAG-Application",
    usecase="Q/A"
)

# 查看可用用例
use_cases = catalyst.project_use_cases()

# 列举所有项目
all_projects = catalyst.list_projects()

步骤 3: 集成追踪功能

from ragaai_catalyst import init_tracing
from ragaai_catalyst.tracers import Tracer

tracer = Tracer(
    project_name="My-RAG-Application",
    dataset_name="production-traces",
    tracer_type="agentic/langgraph",
)

init_tracing(catalyst=catalyst, tracer=tracer)

最佳实践

1. 项目组织建议

• 按业务线或应用类型划分项目
• 为每个项目配置独立的数据集和追踪器
• 使用清晰的项目命名规范

2. 认证安全建议

• 敏感凭证使用环境变量管理
• 避免在代码中硬编码密钥
• 定期轮换访问密钥

3. 追踪配置建议

• 根据应用框架选择正确的 tracer_type
• 为生产环境和开发环境使用不同的数据集
• 定期检查追踪数据上传状态

依赖要求

项目管理的 Python 依赖已包含在主包中，核心依赖包括：

额外测试依赖见 tests_requirements.txt

常见问题

Q: 如何获取认证密钥？

登录 RagaAI Catalyst 平台，进入 Profile Settings → Authentication，点击 Generate New Key 获取。

Q: tracer_type 有哪些可选值？

支持 agentic/langgraph、agentic/langchain、agentic/smolagents、agentic/openai_agents、agentic/llamaindex、agentic/haystack 等类型。

Q: 项目和数据集是什么关系？

一个项目可以包含多个数据集，数据集用于存储评估用的测试数据和追踪记录。

概述

RagaAI Catalyst 的数据集管理模块为用户提供了统一的数据集创建、查询和元数据管理能力。该模块支持从 CSV 文件、DataFrame 或 JSONL 文件导入数据集，并提供了灵活的模式映射（Schema Mapping）功能，使用户能够将数据列映射到系统定义的标准模式元素。

数据集管理在 RagaAI Catalyst 平台中扮演着数据入口的角色，是后续追踪（Tracing）和评估（Evaluation）功能的基础前提。只有在项目下创建了有效的数据集，用户才能配置追踪器捕获应用行为，或运行评估指标分析应用性能。

资料来源：README.md

核心类与导入

数据集管理的核心功能通过 Dataset 类实现，该类封装了所有与数据集操作相关的接口。

from ragaai_catalyst import Dataset

资料来源：docs/quickstart.md

初始化 Dataset 管理器

在使用任何数据集操作之前，需要先初始化 Dataset 管理器实例。初始化时必须指定项目名称，以便在对应的项目上下文中管理数据集。

dataset_manager = Dataset(project_name="project_name")

资料来源：README.md

主要功能

列出已有数据集

用户可以通过 list_datasets() 方法查看指定项目下所有已创建的数据集。

datasets = dataset_manager.list_datasets()
print("Existing Datasets:", datasets)

资料来源：README.md

从 CSV 文件创建数据集

create_from_csv() 方法允许用户从本地 CSV 文件导入数据创建数据集。该方法需要提供文件路径、数据集名称以及列映射配置。

dataset_manager.create_from_csv(
    csv_path='path/to/your.csv',
    dataset_name='MyDataset',
    schema_mapping={'column1': 'schema_element1', 'column2': 'schema_element2'}
)

资料来源：docs/quickstart.md 和 README.md

获取模式映射

创建数据集时定义的模式映射可以通过 get_schema_mapping() 方法查询，用于验证数据列与系统模式元素的对应关系。

print(dataset_manager.get_schema_mapping())

资料来源：README.md

模式映射（Schema Mapping）

模式映射是数据集创建过程中的核心配置项，用于将用户数据中的列名映射到 RagaAI Catalyst 平台定义的标准化模式元素。

标准模式元素

根据评估框架的使用示例，典型的模式映射结构如下：

schema_mapping = {
    'Query': 'prompt',
    'response': 'response',
    'Context': 'context',
    'expectedResponse': 'expected_response'
}

资料来源：docs/quickstart.md

数据集管理流程

graph TD
    A[初始化 Dataset 管理器] --> B{数据源类型}
    B -->|CSV 文件| C[调用 create_from_csv]
    B -->|DataFrame| D[调用 create_from_dataframe]
    B -->|JSONL 文件| E[调用 create_from_jsonl]
    C --> F[定义 schema_mapping]
    D --> F
    E --> F
    F --> G[创建数据集]
    G --> H[验证模式映射]
    H --> I[数据集可用于评估和追踪]

在评估框架中的使用

数据集创建完成后，可以与评估框架集成，用于运行各种评估指标。以下是数据集在评估流程中的典型使用方式：

from ragaai_catalyst import Evaluation

# 使用已创建的数据集初始化评估引擎
evaluation = Evaluation(
    project_name="Project_Name",
    dataset_name="MyDataset"
)

# 定义与数据集对应的 schema_mapping
schema_mapping = {
    'Query': 'prompt',
    'response': 'response',
    'Context': 'context',
    'expectedResponse': 'expected_response'
}

# 添加评估指标
evaluation.add_metrics(
    metrics=[
        {
            "name": "Faithfulness",
            "config": {"model": "gpt-4o-mini", "provider": "openai", "threshold": {"gte": 0.232323}},
            "column_name": "Faithfulness_v1",
            "schema_mapping": schema_mapping
        }
    ]
)

资料来源：docs/quickstart.md

在追踪框架中的使用

数据集同样用于追踪框架，用于存储和检索应用运行过程中的追踪记录：

from ragaai_catalyst import Tracer

tracer = Tracer(
    project_name="Project_Name",
    dataset_name="Dataset_Name",
    tracer_type="agentic/langgraph"
)

资料来源：docs/quickstart.md

最佳实践

1. 命名规范：数据集名称应具有描述性，便于在项目内识别不同数据集的用途
2. 模式映射一致性：确保 schema_mapping 在数据集创建和评估配置中保持一致
3. CSV 文件格式：确保 CSV 文件编码为 UTF-8，且列名与 schema_mapping 的键完全匹配
4. 先创建后使用：在进行评估或追踪之前，确保数据集已成功创建并上传

功能概述

评估管理模块提供以下核心能力：

核心组件

Evaluation 类

Evaluation 类是评估管理的入口点，负责协调整个评估流程。

from ragaai_catalyst import Evaluation

evaluation = Evaluation(
    project_name="项目名称",
    dataset_name="数据集名称"
)

构造函数参数

评估工作流程

graph TD
    A[初始化评估引擎] --> B[定义模式映射]
    B --> C[添加评估指标]
    C --> D[执行评估]
    D --> E[获取评估状态]
    E --> F{状态检查}
    F -->|完成| G[获取评估结果]
    F -->|进行中| E

使用方法

基础用法

from ragaai_catalyst import Evaluation

# 初始化评估引擎
evaluation = Evaluation(
    project_name="Test-RAG-App-1",
    dataset_name="MyDataset"
)

# 获取可用指标列表
available_metrics = evaluation.list_metrics()
print("可用指标:", available_metrics)

配置评估指标

定义模式映射，将数据集列映射到评估框架的标准字段：

# 定义模式映射
schema_mapping = {
    'Query': 'prompt',           # 用户查询字段
    'response': 'response',     # 模型响应字段
    'Context': 'context',       # 上下文/检索结果字段
    'expectedResponse': 'expected_response'  # 期望响应字段
}

# 添加评估指标
evaluation.add_metrics(
    metrics=[
        {
            "name": "Faithfulness",
            "config": {
                "model": "gpt-4o-mini",
                "provider": "openai",
                "threshold": {"gte": 0.5}
            },
            "column_name": "Faithfulness_v1",
            "schema_mapping": schema_mapping
        },
        {
            "name": "AnswerRelevancy",
            "config": {
                "model": "gpt-4o-mini",
                "provider": "openai",
                "threshold": {"gte": 0.7}
            },
            "column_name": "Relevancy_v1",
            "schema_mapping": schema_mapping
        }
    ]
)

指标配置参数说明

获取评估结果

# 获取评估状态
status = evaluation.get_status()
print(f"评估状态: {status}")

# 获取评估结果
results = evaluation.get_results()
print(f"评估结果: {results}")

模式映射配置

模式映射是连接数据集与评估框架的关键配置，用于指定数据集中各字段的语义角色。

标准字段映射

自定义映射示例

schema_mapping = {
    'Query': 'user_question',
    'response': 'assistant_reply',
    'Context': 'retrieved_content',
    'expectedResponse': 'correct_answer'
}

evaluation.add_metrics(
    metrics=[{
        "name": "Faithfulness",
        "config": {"model": "gpt-4o-mini", "provider": "openai"},
        "column_name": "faithfulness_score",
        "schema_mapping": schema_mapping
    }]
)

支持的评估指标

根据代码结构，评估框架支持多种内置指标，开发者可以通过 list_metrics() 方法获取完整的指标列表。

常用指标类型

完整使用示例

from ragaai_catalyst import Evaluation

# 1. 初始化评估引擎
evaluation = Evaluation(
    project_name="Product-RAG-Project",
    dataset_name="Product-QA-Dataset"
)

# 2. 查看可用指标
print("可用评估指标:")
print(evaluation.list_metrics())

# 3. 配置模式映射
schema_mapping = {
    'Query': 'prompt',
    'response': 'llm_response',
    'Context': 'retrieved_context',
    'expectedResponse': 'ground_truth'
}

# 4. 添加多个评估指标
evaluation.add_metrics(
    metrics=[
        {
            "name": "Faithfulness",
            "config": {
                "model": "gpt-4o-mini",
                "provider": "openai",
                "threshold": {"gte": 0.5}
            },
            "column_name": "faithfulness_v1",
            "schema_mapping": schema_mapping
        },
        {
            "name": "AnswerRelevancy",
            "config": {
                "model": "gpt-4o-mini",
                "provider": "openai",
                "threshold": {"gte": 0.7}
            },
            "column_name": "relevancy_v1",
            "schema_mapping": schema_mapping
        }
    ]
)

# 5. 检查评估状态
print(f"状态: {evaluation.get_status()}")

# 6. 获取评估结果
print(f"结果: {evaluation.get_results()}")

集成注意事项

前置条件

• 已创建项目并配置有效的认证凭证
• 已上传包含必要字段的数据集
• 确保数据集字段与模式映射配置匹配

数据集要求

评估数据集应包含以下字段：

1. prompt - 用户查询文本
2. response - LLM 生成的回答
3. context - 相关的上下文或检索结果
4. expected_response - 预期的正确答案（可选）

错误处理

try:
    evaluation = Evaluation(
        project_name="NonExistentProject",
        dataset_name="TestDataset"
    )
    evaluation.add_metrics(metrics=[...])
except Exception as e:
    print(f"评估初始化失败: {e}")

与其他模块的协作

评估管理模块与其他 RagaAI Catalyst 组件的关系：

graph LR
    A[项目] --> B[数据集]
    B --> C[评估管理]
    C --> D[评估指标]
    D --> E[评估结果]
    
    F[追踪管理] --> C
    G[提示词管理] --> C

评估结果可与追踪管理模块结合使用，实现端到端的 LLM 应用监控与优化。

概述

提示词管理（Prompt Management）是 RagaAI Catalyst 平台的核心功能模块之一，旨在帮助开发者高效地管理、存储、版本控制和编译提示词模板。该模块提供了统一的接口，使开发者能够在项目中灵活地使用提示词，并支持变量插值、版本管理和动态编译等功能。

提示词管理的核心价值在于将提示词从业务代码中分离出来，实现提示词的集中管理和复用，从而提升应用程序的可维护性和灵活性。开发者可以通过 PromptManager 类与平台进行交互，完成提示词的查询、获取和编译等操作。

核心组件

PromptManager 类

PromptManager 是提示词管理的入口类，提供了完整的提示词生命周期管理功能。

from ragaai_catalyst import PromptManager

# 初始化 PromptManager
prompt_manager = PromptManager(project_name="Test-RAG-App-1")

初始化参数：

资料来源：README.md:1-15

Prompt 对象

Prompt 对象代表一个具体的提示词模板，包含以下核心方法：

资料来源：README.md:20-35

功能特性

列表查询功能

#### 列出可用提示词

通过 list_prompts() 方法可以获取项目下所有可用的提示词模板：

# 列出所有可用提示词
prompts = prompt_manager.list_prompts()
print("Available prompts:", prompts)

该方法返回提示词名称列表，开发者可以根据实际需求选择合适的提示词进行使用。

#### 获取特定提示词

根据提示词名称获取提示词对象，支持获取最新版本或指定版本：

# 获取默认版本提示词
prompt = prompt_manager.get_prompt(prompt_name)

# 获取指定版本提示词
prompt = prompt_manager.get_prompt(prompt_name, version="v1")

参数说明：

资料来源：README.md:15-25

变量提取功能

提示词通常包含动态变量，开发者可以通过 get_variables() 方法提取这些变量：

# 获取提示词中的变量
variable = prompt.get_variables()
print("variable:", variable)

该方法返回一个字典，包含提示词中定义的所有变量名称及其默认值（如果有）。

提示词内容获取

获取提示词的原始模板内容：

# 获取提示词原始内容
prompt_content = prompt.get_prompt_content()
print("prompt_content:", prompt_content)

返回的 prompt_content 是模板字符串，其中包含变量占位符，通常使用 {{variable_name}} 或 {variable_name} 格式。

提示词编译

#### 基本编译

使用 compile() 方法将变量值注入到提示词模板中：

# 编译提示词
compiled_prompt = prompt.compile(
    query="What's the weather?",
    context="sunny",
    llm_response="It's sunny today"
)
print("Compiled prompt:", compiled_prompt)

参数说明：

#### 编译结果使用

编译后的提示词可以直接用于 LLM 调用：

import openai

def get_openai_response(prompt):
    client = openai.OpenAI()
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=prompt
    )
    return response.choices[0].message.content

# 使用编译后的提示词获取响应
result = get_openai_response(compiled_prompt)

资料来源：README.md:30-55

工作流程

标准使用流程

graph TD
    A[初始化 PromptManager] --> B[列出可用提示词]
    B --> C[选择提示词名称]
    C --> D[获取提示词对象]
    D --> E[提取变量列表]
    E --> F[准备变量值]
    F --> G[编译提示词]
    G --> H[集成到 LLM 调用]
    H --> I[获取响应结果]

版本管理流程

graph TD
    A[获取提示词] --> B{指定版本?}
    B -->|是| C[传入 version 参数]
    B -->|否| D[获取最新版本]
    C --> E[验证版本有效性]
    D --> E
    E --> F{版本存在?}
    F -->|是| G[返回提示词对象]
    F -->|否| H[抛出异常]

应用场景

问答系统

在问答系统中，提示词管理可以用于：

• 管理不同类型的问答模板
• 支持上下文注入
• 处理多轮对话场景

RAG 应用

在检索增强生成（RAG）应用中，提示词管理发挥着重要作用：

• 管理检索上下文模板
• 处理多文档场景
• 支持自定义生成风格

Agent 应用

对于 Agent 应用，提示词管理支持：

• 工具调用指令模板
• 系统提示词管理
• 角色定义模板

资料来源：examples/crewai/scifi_writer/scifi_writer.py:1-80

配置与集成

环境配置

提示词管理功能需要与 RagaAICatalyst 配合使用，需要配置以下凭证：

import os
from dotenv import load_dotenv

load_dotenv()

# 从环境变量或配置文件获取凭证
access_key = os.getenv('RAGAAI_CATALYST_ACCESS_KEY')
secret_key = os.getenv('RAGAAI_CATALYST_SECRET_KEY')
base_url = os.getenv('RAGAAI_CATALYST_BASE_URL')
project_name = os.getenv('RAGAAI_PROJECT_NAME')

与追踪系统集成

提示词管理可以与 RagaAI 的追踪系统无缝集成：

from ragaai_catalyst import RagaAICatalyst, init_tracing
from ragaai_catalyst.tracers import Tracer

# 初始化催化剂实例
catalyst = RagaAICatalyst(
    access_key=access_key,
    secret_key=secret_key,
    base_url=base_url
)

# 初始化追踪器
tracer = Tracer(
    project_name=project_name,
    dataset_name="tracer_dataset_name",
    tracer_type="agentic/langchain"
)

# 启用自动追踪
init_tracing(catalyst=catalyst, tracer=tracer)

资料来源：examples/langchain/medical_rag/diagnosis_agent.py:1-35

最佳实践

提示词设计原则

1. 变量命名清晰：使用描述性的变量名称，便于理解和使用
2. 版本控制：为重要提示词添加版本号，便于追踪变更
3. 模块化设计：将复杂提示词拆分为可复用的模块
4. 文档完善：为提示词添加说明和示例

性能优化

1. 缓存提示词对象：避免重复获取相同的提示词
2. 批量编译：对于大量相似请求，考虑批量处理
3. 异步调用：在需要时使用异步方式获取提示词

安全考虑

1. 敏感信息处理：避免在提示词中硬编码敏感信息
2. 访问控制：确保只有授权用户可以修改提示词
3. 审计日志：记录提示词的访问和修改历史

相关模块

常见问题

Q: 如何处理提示词版本冲突？

A: 建议在获取提示词时明确指定版本号，避免因默认版本更新导致的行为差异。

Q: 提示词编译失败怎么办？

A: 首先检查变量名称是否与模板定义一致，其次确认所有必填变量都已提供。

Q: 如何管理大量提示词？

A: 建议按功能模块或应用场景对提示词进行分组，使用规范化的命名约定便于检索。

总结

提示词管理是 RagaAI Catalyst 平台的重要功能，通过提供统一的接口和完善的管理机制，帮助开发者更高效地管理和使用提示词模板。该模块支持版本控制、变量提取、动态编译等核心功能，可以广泛应用于问答系统、RAG 应用和 Agent 应用等多种场景。与平台的追踪、评估等模块配合使用，能够构建完整的 AI 应用开发工作流。

概述

智能体追踪系统（Agentic Tracing System）是 RagaAI Catalyst 平台的核心组件之一，旨在为基于大语言模型的智能体应用提供全面的可观测性解决方案。该系统通过自动插桩和自定义追踪两种模式，捕获智能体执行过程中的关键信息，包括 LLM 调用、工具执行、代理行为、用户交互、文件操作和网络通信等各个环节。

智能体追踪系统支持多种主流 AI 框架的深度集成，包括 LangGraph、LangChain、CrewAI、SmolaAgents、OpenAI Agents 和 LlamaIndex 等。系统将这些框架的执行轨迹统一标准化后上传至 RagaAI 云端平台，便于开发者进行性能分析、调试和优化。

资料来源：docs/agentic_tracing.md

架构设计

整体架构

智能体追踪系统采用分层架构设计，从底层到顶层依次包括数据采集层、标准化处理层和上传服务层。各层之间通过事件驱动的方式进行通信，确保追踪数据的完整性和时效性。

graph TD
    A[应用层] --> B[自动插桩层]
    A --> C[手动追踪层]
    B --> D[事件收集器]
    C --> D
    D --> E[数据标准化处理器]
    E --> F[轨迹导出器]
    F --> G[RagaAI 云端平台]
    
    B -.-> H[LLM 插桩]
    B -.-> I[工具插桩]
    B -.-> J[代理插桩]
    B -.-> K[用户交互插桩]
    B -.-> L[文件IO插桩]
    B -.-> M[网络插桩]
    B -.-> N[自定义插桩]

核心组件

资料来源：ragaai_catalyst/tracers/tracer.py:1-50

支持的追踪器类型

智能体追踪系统通过 tracer_type 参数区分不同的追踪目标。系统支持两大类追踪模式：智能体类追踪器和RAG 类追踪器。

智能体类追踪器

资料来源：ragaai_catalyst/tracer.py:60-80

RAG 类追踪器

通用智能体追踪器

当 tracer_type 设置为 agentic（不含具体框架后缀）时，系统将启用通用智能体追踪模式，同时支持 VertexAI、Anthropic、LiteLLM、OpenAI 等多个 LLM 提供商的插桩。

资料来源：ragaai_catalyst/tracer.py:80-150

快速入门

环境配置

在使用智能体追踪系统之前，需要确保已完成以下配置：

pip install ragaai-catalyst

并设置环境变量或在代码中初始化认证信息：

import os
from ragaai_catalyst import RagaAICatalyst

catalyst = RagaAICatalyst(
    access_key=os.getenv("RAGAAI_CATALYST_ACCESS_KEY"),
    secret_key=os.getenv("RAGAAI_CATALYST_SECRET_KEY"),
    base_url=os.getenv("RAGAAI_CATALYST_BASE_URL"),
)

资料来源：examples/all_llm_provider/config.py:1-20

自动插桩模式

自动插桩是智能体追踪系统最便捷的使用方式。只需初始化追踪器并调用 init_tracing 函数，系统即可自动捕获应用中的各类操作。

from ragaai_catalyst import RagaAICatalyst, init_tracing
from ragaai_catalyst.tracers import Tracer

# 初始化 RagaAI Catalyst
catalyst = RagaAICatalyst(
    access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),
    secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),
    base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')
)

# 创建追踪器
tracer = Tracer(
    project_name=os.getenv('RAGAAI_PROJECT_NAME'),
    dataset_name=os.getenv('RAGAAI_DATASET_NAME'),
    tracer_type="agentic/langgraph"  # 根据实际框架选择
)

# 启用自动插桩
init_tracing(catalyst=catalyst, tracer=tracer)

资料来源：docs/agentic_tracing.md

自定义追踪模式

对于需要精确控制追踪范围和时机的场景，系统提供两种自定义追踪方式：

#### 方式一：上下文管理器方式

from ragaai_catalyst import Tracer

tracer = Tracer(
    project_name="Project_Name",
    dataset_name="tracer_dataset_name",
    tracer_type="agentic/langgraph"
)

with tracer():
    # 需要追踪的代码块
    result = your_agent.run("用户输入")

#### 方式二：手动启停方式

tracer.start()

# 需要追踪的代码
result = your_agent.run("用户输入")

tracer.stop()

# 验证数据上传状态
print(tracer.get_upload_status())

资料来源：docs/agentic_tracing.md

Tracer 类详解

构造函数参数

资料来源：ragaai_catalyst/tracers/tracer.py:30-70

自动插桩配置

auto_instrumentation 参数用于精细控制自动插桩的范围，默认配置如下：

auto_instrumentation = {
    'llm': True,           # LLM 调用追踪
    'tool': True,          # 工具执行追踪
    'agent': True,         # 代理行为追踪
    'user_interaction': True,  # 用户交互追踪
    'file_io': True,       # 文件操作追踪
    'network': True,       # 网络请求追踪
    'custom': True         # 自定义事件追踪
}

资料来源：ragaai_catalyst/tracers/tracer.py:40-50

模型成本配置

系统支持设置自定义模型成本，用于追踪 LLM 调用费用：

tracer.set_model_cost({
    "model_name": "gpt-4",
    "input_cost_per_million_token": 6,
    "output_cost_per_million_token": 2.40
})

资料来源：ragaai_catalyst/tracers/tracer.py:100-130

与各框架的集成

CrewAI 集成

CrewAI 是多智能体协作框架，RagaAI Catalyst 提供原生的 CrewAI 追踪支持：

from crewai import Agent, Task, Crew, Process
from ragaai_catalyst import RagaAICatalyst, init_tracing
from ragaai_catalyst.tracers import Tracer

# 初始化追踪
catalyst = RagaAICatalyst(
    access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),
    secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),
    base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')
)

tracer = Tracer(
    project_name=os.getenv('RAGAAI_PROJECT_NAME'),
    dataset_name=os.getenv('RAGAAI_DATASET_NAME'),
    tracer_type="agentic/crewai",
)
init_tracing(catalyst=catalyst, tracer=tracer)

# 创建 CrewAI 应用
brainstormer = Agent(
    role="创意生成器",
    goal="生成创意性想法",
    backstory="你是一位富有想象力的思考者"
)

crew = Crew(
    agents=[brainstormer],
    tasks=[brainstorm_task],
    process=Process.sequential
)

result = crew.kickoff()

资料来源：examples/crewai/scifi_writer/scifi_writer.py:1-80

SmolaAgents 集成

SmolaAgents 是轻量级智能体框架，适用于简单到中等复杂度的任务：

from ragaai_catalyst import RagaAICatalyst, init_tracing
from ragaai_catalyst.tracers import Tracer

catalyst = RagaAICatalyst(
    access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),
    secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),
    base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')
)

tracer = Tracer(
    project_name=os.getenv('RAGAAI_PROJECT_NAME'),
    dataset_name=os.getenv('RAGAAI_DATASET_NAME'),
    tracer_type="agentic/smolagents",
)
init_tracing(catalyst=catalyst, tracer=tracer)

资料来源：examples/smolagents/most_upvoted_paper/README.md

自定义代理集成

对于自定义代理应用，系统提供通用的智能体追踪支持：

from ragaai_catalyst import RagaAICatalyst, init_tracing
from ragaai_catalyst.tracers import Tracer

def initialize_tracing():
    catalyst = RagaAICatalyst(
        access_key=os.getenv("RAGAAI_CATALYST_ACCESS_KEY"),
        secret_key=os.getenv("RAGAAI_CATALYST_SECRET_KEY"),
        base_url=os.getenv("RAGAAI_CATALYST_BASE_URL"),
    )

    tracer = Tracer(
        project_name=os.getenv("RAGAAI_PROJECT_NAME"),
        dataset_name=os.getenv("RAGAAI_DATASET_NAME"),
        tracer_type="Agentic",  # 通用智能体模式
    )

    init_tracing(catalyst=catalyst, tracer=tracer)
    return tracer

资料来源：examples/custom_agents/travel_agent/config.py:1-30

工作流程

智能体追踪系统的工作流程可划分为以下四个阶段：

graph LR
    A[初始化] --> B[配置追踪器]
    B --> C[自动插桩/手动追踪]
    C --> D[数据收集]
    D --> E[数据标准化]
    E --> F[上传至云端]
    F --> G[查看分析结果]

阶段一：初始化

在应用启动时，首先创建 RagaAICatalyst 实例和 Tracer 实例，建立与 RagaAI 平台的连接。

阶段二：配置追踪器

根据实际使用的框架选择合适的 tracer_type，并通过 init_tracing 函数启用自动插桩功能。

阶段三：执行追踪

应用运行时，追踪器自动捕获各类操作事件。对于需要特定追踪范围的场景，可使用上下文管理器或手动启停方式。

阶段四：数据上传

追踪数据经过标准化处理后，通过后台任务异步上传至 RagaAI 云端平台。用户可通过 get_upload_status() 方法查看上传状态。

系统资源监控

智能体追踪系统集成了系统资源监控功能，用于记录追踪期间的系统环境信息：

资料来源：ragaai_catalyst/tracers/agentic_tracing/utils/system_monitor.py:20-80

最佳实践

选择合适的追踪模式

性能考虑

• 默认上传间隔为 2 秒，可通过 interval_time 参数调整
• 最大上传线程数为 30，可通过 max_upload_workers 参数调整
• 对于高频调用场景，建议适当增大 interval_time 以减少网络开销

安全性建议

• 妥善保管 access_key 和 secret_key，避免硬编码在代码中
• 推荐使用环境变量或配置中心管理敏感信息
• 定期轮换认证凭证

故障排查

常见问题

调试模式

启用调试模式以获取详细日志：

import os
os.environ["DEBUG"] = "1"

设置后，追踪器将输出详细的调试信息，便于定位问题。

总结

智能体追踪系统是 RagaAI Catalyst 平台的核心功能之一，通过统一的标准化的追踪机制，为开发者提供跨框架的可观测性解决方案。该系统支持灵活的自动插桩和自定义追踪两种模式，兼容多种主流 AI 框架，并提供完整的资源监控和数据分析能力。无论是快速原型开发还是生产环境监控，智能体追踪系统都能提供有力的技术支持。

概述

RagaAI Catalyst 的追踪器（Tracer）系统为各种 AI 代理和 LLM 框架提供统一的追踪和监控能力。通过支持多种主流框架，开发者可以在不同的技术栈中实现一致的追踪体验。

追踪器类型的核心作用是根据不同的框架自动配置相应的检测器（Instrumentors），并通过统一的接口管理追踪生命周期，包括启动、停止和上传追踪数据。

资料来源：ragaai_catalyst/tracers/tracer.py:1-50

支持的追踪器类型

追踪器类型总览

RagaAI Catalyst 支持以下追踪器类型：

资料来源：ragaai_catalyst/tracers/tracer.py:45-90

框架支持架构

架构层次

graph TD
    A[Tracer 追踪器主类] --> B[AgenticTracing 基础类]
    B --> C[框架特定检测器]
    
    C --> D[LLM 检测器]
    C --> E[Tool 检测器]
    C --> F[Agent 检测器]
    C --> G[User Interaction 检测器]
    
    D --> D1[LiteLLMInstrumentor]
    D --> D2[OpenAIInstrumentor]
    D --> D3[AnthropicInstrumentor]
    D --> D4[GroqInstrumentor]
    D --> D5[VertexAIInstrumentor]
    
    E --> E1[Tool Callbacks]
    F --> F1[Agent Callbacks]
    G --> G1[User Interaction Callbacks]
    
    H[RAGATraceExporter] --> I[追踪数据上传]

追踪器初始化流程

sequenceDiagram
    participant User as 用户
    participant Tracer as Tracer 类
    participant Setup as 框架设置
    participant Instrumentor as 检测器
    
    User->>Tracer: 初始化 Tracer(tracer_type)
    Tracer->>Tracer: 验证 tracer_type
    Tracer->>Setup: 调用框架特定设置
    Setup->>Instrumentor: 加载对应 Instrumentors
    Instrumentor-->>Setup: 返回检测器实例
    Setup-->>Tracer: 完成配置
    Tracer-->>User: 返回 Tracer 实例

资料来源：ragaai_catalyst/tracers/tracer.py:60-120

追踪器核心参数

Tracer 类初始化参数

auto_instrumentation 配置

auto_instrumentation 参数控制自动检测的组件类型：

资料来源：ragaai_catalyst/tracers/tracer.py:30-45

框架集成示例

LangGraph 框架集成

from ragaai_catalyst import RagaAICatalyst, init_tracing
from ragaai_catalyst.tracers import Tracer

catalyst = RagaAICatalyst(
    access_key="YOUR_ACCESS_KEY",
    secret_key="YOUR_SECRET_KEY",
    base_url="BASE_URL"
)

tracer = Tracer(
    project_name="my-project",
    dataset_name="my-dataset",
    tracer_type="agentic/langgraph"
)

init_tracing(catalyst=catalyst, tracer=tracer)

资料来源：examples/langgraph/personal_research_assistant/research_assistant.py:20-35

CrewAI 框架集成

from ragaai_catalyst import RagaAICatalyst, init_tracing
from ragaai_catalyst.tracers import Tracer

catalyst = RagaAICatalyst(
    access_key=os.getenv('RAGAAI_CATALYST_ACCESS_KEY'),
    secret_key=os.getenv('RAGAAI_CATALYST_SECRET_KEY'),
    base_url=os.getenv('RAGAAI_CATALYST_BASE_URL')
)

tracer = Tracer(
    project_name=os.getenv('RAGAAI_PROJECT_NAME'),
    dataset_name=os.getenv('RAGAAI_DATASET_NAME'),
    tracer_type="agentic/crewai"
)

init_tracing(catalyst=catalyst, tracer=tracer)

资料来源：examples/crewai/scifi_writer/scifi_writer.py:10-25

SmolAgents 框架集成

SmolAgents 框架通过 SmolagentsInstrumentor 进行检测：

tracer = Tracer(
    project_name="project_name",
    dataset_name="dataset_name",
    tracer_type="agentic/smolagents"
)

自定义代理集成

from ragaai_catalyst import RagaAICatalyst, init_tracing
from ragaai_catalyst.tracers import Tracer

catalyst = RagaAICatalyst(
    access_key=os.getenv("RAGAAI_CATALYST_ACCESS_KEY"),
    secret_key=os.getenv("RAGAAI_CATALYST_SECRET_KEY"),
    base_url=os.getenv("RAGAAI_CATALYST_BASE_URL")
)

tracer = Tracer(
    project_name=os.getenv("RAGAAI_PROJECT_NAME"),
    dataset_name=os.getenv("RAGAAI_DATASET_NAME"),
    tracer_type="Agentic"  # 通用代理追踪
)

init_tracing(catalyst=catalyst, tracer=tracer)

资料来源：examples/custom_agents/travel_agent/config.py:10-25

LLM 检测器支持

RagaAI Catalyst 支持多种 LLM 提供商的检测：

检测器自动根据 tracer_type 进行加载：

if tracer_type in ['agentic/crewai']:
    from openinference.instrumentation.vertexai import VertexAIInstrumentor
    instrumentors.append((VertexAIInstrumentor, []))
    from openinference.instrumentation.anthropic import AnthropicInstrumentor
    instrumentors.append((AnthropicInstrumentor, []))
    from openinference.instrumentation.groq import GroqInstrumentor
    instrumentors.append((GroqInstrumentor, []))
    from openinference.instrumentation.litellm import LiteLLMInstrumentor
    instrumentors.append((LiteLLMInstrumentor, []))

资料来源：ragaai_catalyst/tracers/tracer.py:65-85

追踪生命周期管理

追踪启动和停止

RagaAI Catalyst 提供两种追踪控制方式：

#### 方式一：上下文管理器

from ragaai_catalyst import Tracer

tracer = Tracer(
    project_name="Project_Name",
    dataset_name="Dataset_Name",
    tracer_type="agentic/langgraph"
)

with tracer():
    # 您的代码逻辑
    pass

#### 方式二：手动控制

from ragaai_catalyst import Tracer

tracer = Tracer(
    project_name="Project_Name",
    dataset_name="Dataset_Name",
    tracer_type="agentic/langgraph"
)

tracer.start()
# 您的代码逻辑
tracer.stop()

# 验证上传状态
print(tracer.get_upload_status())

资料来源：quickstart.md

不同框架的启动行为

def start(self):
    if self.tracer_type == "langchain":
        super().start()
        return self
    elif self.tracer_type == "llamaindex":
        self.llamaindex_tracer = LlamaIndexInstrumentationTracer(self._pass_user_data())
        return self.llamaindex_tracer.start()
    else:
        super().start()
        return self

资料来源：ragaai_catalyst/tracers/tracer.py:180-195

自动检测与手动检测

自动检测（Auto-Instrumentation）

自动检测在初始化时启用，可通过 init_tracing 函数配置：

from ragaai_catalyst import init_tracing, Tracer

tracer = Tracer(
    project_name="Project_Name",
    dataset_name="Dataset_Name",
    tracer_type="agentic/langgraph"
)

init_tracing(catalyst=catalyst, tracer=tracer)

自动检测组件控制

可通过 auto_instrumentation 参数精细控制：

tracer = Tracer(
    project_name="Project_Name",
    dataset_name="Dataset_Name",
    tracer_type="agentic/langgraph",
    auto_instrumentation={
        'llm': True,           # 启用 LLM 追踪
        'tool': True,          # 启用工具追踪
        'agent': True,         # 启用代理追踪
        'user_interaction': True,  # 启用用户交互追踪
        'file_io': True,       # 启用文件 IO 追踪
        'network': True,       # 启用网络请求追踪
        'custom': True          # 启用自定义追踪
    }
)

框架特定检测器

资料来源：ragaai_catalyst/tracers/tracer.py:90-115

模型成本追踪

设置自定义模型成本

RagaAI Catalyst 支持追踪 LLM 调用成本：

tracer.set_model_cost({
    "model_name": "gpt-4",
    "input_cost_per_million_token": 6,
    "output_cost_per_million_token": 2.40
})

成本追踪参数

可通过 update_llm_cost=False 禁用成本更新：

tracer = Tracer(
    project_name="project",
    dataset_name="dataset",
    tracer_type="agentic/langgraph",
    update_llm_cost=False
)

资料来源：ragaai_catalyst/tracers/tracer.py:125-145

快速参考

追踪器类型选择指南

最小配置示例

from ragaai_catalyst import RagaAICatalyst, init_tracing, Tracer

# 初始化 Catalyst
catalyst = RagaAICatalyst(
    access_key="YOUR_ACCESS_KEY",
    secret_key="YOUR_SECRET_KEY"
)

# 创建追踪器
tracer = Tracer(
    project_name="my-project",
    dataset_name="my-dataset",
    tracer_type="agentic/langgraph"
)

# 启用追踪
init_tracing(catalyst=catalyst, tracer=tracer)

# 使用上下文管理器运行代码
with tracer():
    # 您的代理代码
    pass

资料来源：README.md

错误处理与调试

常见问题处理

调试模式

启用调试模式查看详细日志：

export DEBUG=1

或在代码中设置日志级别：

import logging
logging.basicConfig(level=logging.DEBUG)

资料来源：ragaai_catalyst/tracers/tracer.py:15-20

概述

合成数据生成（Synthetic Data Generation）是 RagaAI Catalyst 平台提供的重要功能模块之一。该模块允许用户通过 LLM（大型语言模型）自动生成测试数据集，用于 RAG 应用的质量评估和测试场景构建。

在 RAG（检索增强生成）应用开发过程中，高质量测试数据的获取往往是开发者面临的主要挑战之一。合成数据生成功能通过利用强大的语言模型能力，帮助开发者快速创建多样化的测试用例，从而提升应用的质量和鲁棒性。

核心功能特性

RagaAI Catalyst 的合成数据生成模块具有以下核心能力：

系统架构

合成数据生成模块在 RagaAI Catalyst 整体架构中扮演着数据准备的关键角色。以下是平台的核心架构图：

graph TD
    A[RagaAI Catalyst] --> B[项目管理]
    A --> C[数据集管理]
    A --> D[评估框架]
    A --> E[跟踪系统]
    A --> F[提示词管理]
    A --> G[Guardrail 管理]
    A --> H[红队测试]
    A --> I[合成数据生成]
    
    I --> I1[数据源配置]
    I --> I2[Schema 映射]
    I --> I3[生成引擎]
    I --> I4[质量验证]
    
    C --> C1[CSV 导入]
    C --> C2[DataFrame 导入]
    C --> C3[JSONL 导入]

工作流程

合成数据生成的标准工作流程包含以下步骤：

graph TD
    A[初始化 RagaAICatalyst] --> B[配置数据集管理器]
    B --> C[定义 Schema 映射]
    C --> D[调用合成数据生成接口]
    D --> E[执行 LLM 生成]
    E --> F[质量验证]
    F --> G{验证通过?}
    G -->|是| H[保存生成的数据]
    G -->|否| I[重新生成或调整参数]
    I --> D
    H --> J[集成到评估流程]

使用方法

初始化配置

使用合成数据生成功能前，需要完成基础配置：

from ragaai_catalyst import RagaAICatalyst

catalyst = RagaAICatalyst(
    access_key="YOUR_ACCESS_KEY",
    secret_key="YOUR_SECRET_KEY",
    base_url="BASE_URL"
)

数据集管理集成

合成数据生成与数据集管理模块紧密集成，支持将生成的数据直接导入到项目数据集中：

from ragaai_catalyst import Dataset

dataset_manager = Dataset(project_name="Project_Name")

# 创建数据集
dataset_manager.create_from_csv(
    csv_path="path/to/your.csv",
    dataset_name="SyntheticDataset",
    schema_mapping={
        'column1': 'schema_element1',
        'column2': 'schema_element2'
    }
)

与评估框架的集成

合成数据生成的主要用途之一是为评估框架提供测试数据。评估框架支持多种内置指标：

from ragaai_catalyst import Evaluation

evaluation = Evaluation(
    project_name="Project_Name",
    dataset_name="SyntheticDataset"
)

# 添加评估指标
schema_mapping = {
    'Query': 'prompt',
    'response': 'response',
    'Context': 'context',
    'expectedResponse': 'expected_response'
}

evaluation.add_metrics(
    metrics=[
        {
            "name": "Faithfulness",
            "config": {"model": "gpt-4o-mini", "provider": "openai", "threshold": {"gte": 0.5}},
            "column_name": "Faithfulness_v1",
            "schema_mapping": schema_mapping
        }
    ]
)

支持的 LLM 提供商

合成数据生成功能支持多种 LLM 提供商，包括：

支持的追踪器类型包括：agentic/langgraph、agentic/langchain、agentic/smolagents、agentic/openai_agents、agentic/llamaindex、agentic/haystack 等。

最佳实践

1. Schema 设计建议

在设计合成数据的 Schema 时，应注意以下要点：

• 确保字段命名清晰且具有描述性
• 定义明确的字段类型和数据约束
• 合理规划必填字段和可选字段

2. 数据质量控制

建议在生成合成数据后进行以下质量检查：

• 验证数据的完整性和一致性
• 检查数据分布的合理性
• 确保生成的问答对具有逻辑性

3. 与真实数据结合

最佳实践建议将合成数据与真实数据结合使用：

• 使用合成数据补充边缘案例
• 使用真实数据验证合成数据的质量
• 定期更新合成数据以覆盖新场景

相关模块

合成数据生成与其他 RagaAI Catalyst 模块协同工作：

• 数据集管理：存储和管理生成的合成数据
• 评估框架：使用合成数据进行模型评估
• 提示词管理：优化数据生成的提示词模板
• 跟踪系统：监控数据生成过程的性能

总结

合成数据生成是 RagaAI Catalyst 平台中用于自动化测试数据创建的核心功能。通过与多种 LLM 提供商的集成，开发者可以灵活地生成高质量的测试数据集，有效提升 RAG 应用的开发和评估效率。该功能与平台的数据集管理、评估框架等模块紧密集成，为用户提供了一整套完整的数据准备和评估解决方案。

概述

安全护栏管理（Guardrail Management）是RagaAI Catalyst平台的核心功能模块之一，旨在为AI应用提供实时的输入输出安全检查与过滤机制。该模块通过预定义的检测器和自定义规则，对LLM（大型语言模型）的输入提示词和生成内容进行多维度安全评估，确保AI应用在预设的安全边界内运行。

安全护栏管理的主要职责包括：

• 输入护栏：在用户输入到达LLM之前进行内容审查和过滤
• 输出护栏：对模型生成的回答进行安全合规性检查
• 策略配置：支持用户自定义检测规则和响应策略
• 结果追踪：记录每次安全检查的执行结果和决策依据

资料来源：README.md:1-15

核心组件架构

RagaAI Catalyst的安全护栏系统由两个核心模块组成，它们协同工作以提供完整的安全保护能力。

graph TD
    A[用户输入] --> B[Guardrails Manager]
    B --> C{检测器选择}
    C --> D[内置检测器]
    C --> E[自定义检测器]
    D --> F[Guard Executor]
    E --> F
    F --> G[安全决策]
    G --> H{通过?}
    H -->|是| I[转发至LLM]
    H -->|否| J[拦截/过滤]
    I --> K[LLM响应]
    K --> L[输出护栏检查]
    L --> M{合规?}
    M -->|是| N[返回用户]
    M -->|否| O[内容过滤]
    J --> P[返回安全响应]
    O --> P
    N --> P

Guardrails Manager

GuardrailsManager是护栏系统的主入口模块，负责护栏实例的创建、配置和管理。该模块提供了统一的API接口，使开发者能够便捷地集成安全护栏功能到现有应用中。

主要功能特性：

• 实例生命周期管理：创建、配置、激活和停用护栏实例
• 检测器注册：支持注册内置检测器和自定义检测器
• 规则链配置：定义多个检测器的执行顺序和组合逻辑
• 运行时配置：支持热更新检测规则而无需重启应用

Guard Executor

GuardExecutor是护栏系统的执行引擎，负责实际运行安全检查逻辑并返回决策结果。该模块封装了底层的检测算法和策略评估逻辑。

核心职责：

• 检测执行：调用已注册的检测器对输入/输出进行评估
• 策略评估：根据配置的策略规则做出最终决策
• 结果聚合：合并多个检测器的结果生成统一报告
• 异常处理：处理检测过程中的异常情况并提供降级策略

资料来源：guardrails_manager.py:1-50

核心数据结构

安全护栏系统使用以下关键数据结构来描述检测规则和执行结果。

检测器定义

护栏执行结果

资料来源：guard_executor.py:1-80

初始化与配置

在使用安全护栏功能之前，需要正确初始化相关的配置。

基础配置

安全护栏模块通过RagaAI Catalyst的统一认证体系进行身份验证。开发者需要在环境变量中配置以下凭证：

初始化代码示例：

import os
from ragaai_catalyst import RagaAICatalyst

# 初始化RagaAI Catalyst客户端
catalyst = RagaAICatalyst(
    access_key=os.getenv("RAGAAI_CATALYST_ACCESS_KEY"),
    secret_key=os.getenv("RAGAAI_CATALYST_SECRET_KEY"),
    base_url=os.getenv("RAGAAI_CATALYST_BASE_URL"),
)

资料来源：examples/custom_agents/travel_agent/config.py:1-20

护栏管理器初始化

创建护栏管理器实例并配置检测器：

from ragaai_catalyst import GuardrailsManager

# 创建护栏管理器
guardrails = GuardrailsManager(
    project_name="my_secure_app",
    dataset_name="guardrails_config",
    detector_config=[
        {
            "name": "harmful_content",
            "type": "builtin",
            "threshold": 0.7,
            "action": "block"
        },
        {
            "name": "personal_info",
            "type": "custom",
            "description": "检测个人信息泄露",
            "threshold": 0.5,
            "action": "warn"
        }
    ]
)

内置检测器

RagaAI Catalyst提供了多种内置检测器，覆盖常见的安全风险场景。

可用内置检测器

自定义检测器

除了内置检测器外，开发者可以创建自定义检测器来满足特定业务需求：

# 定义自定义检测器配置
custom_detector = {
    "name": "prevent_sensitive_topics",
    "type": "custom",
    "description": "防止讨论敏感话题",
    "config": {
        "blocked_topics": ["politics", "religion", "conspiracy"],
        "match_mode": "any"  # 或 "all"
    },
    "threshold": 0.5,
    "action": "block"
}

执行流程

安全护栏的执行遵循标准的处理流程，确保每个请求都经过适当的安全检查。

graph TD
    A[接收输入请求] --> B[参数验证]
    B --> C{参数有效?}
    C -->|否| D[返回验证错误]
    C -->|是| E[加载检测器配置]
    E --> F[执行输入护栏]
    F --> G[遍历检测器列表]
    G --> H{当前检测器}
    H -->|内置| I[调用内置检测逻辑]
    H -->|自定义| J[调用自定义检测逻辑]
    I --> K[计算风险评分]
    J --> K
    K --> L{评分>=阈值?}
    L -->|是| M[记录违规项]
    L -->|否| N[继续下一检测器]
    M --> O[触发对应动作]
    O --> N
    N --> P{还有检测器?}
    P -->|是| G
    P -->|否| Q[汇总检查结果]
    Q --> R{全部通过?}
    R -->|是| S[转发至LLM处理]
    R -->|否| T[执行拦截/过滤]
    S --> U[获取LLM响应]
    U --> V[执行输出护栏]
    V --> W[返回最终响应]
    T --> W

集成使用模式

安全护栏系统支持多种集成方式，以适应不同的应用架构场景。

模式一：独立护栏服务

在独立的微服务架构中部署护栏功能：

from ragaai_catalyst import GuardrailsManager, GuardExecutor

# 创建护栏管理器和执行器
guardrails_manager = GuardrailsManager(
    project_name="guardrail_service",
    detector_config=[...]
)

guard_executor = GuardExecutor(
    detectors=guardrails_manager.get_detectors()
)

def process_request(user_input):
    # 执行输入检查
    result = guard_executor.execute(
        content=user_input,
        direction="input"
    )
    
    if not result.passed:
        return {"error": "内容不符合安全要求", "details": result.detections}
    
    # 继续处理流程
    return llm.process(user_input)

模式二：中间件集成

将护栏功能作为中间件集成到现有应用框架中：

from ragaai_catalyst import GuardrailsMiddleware

# 创建护栏中间件
guardrails_middleware = GuardrailsMiddleware(
    detector_config=[...],
    middleware_config={
        "log_all_requests": True,
        "fail_open": False  # 安全失败模式
    }
)

# 应用中间件
app.add_middleware(guardrails_middleware)

资料来源：quickstart.md:50-100

最佳实践

配置优化建议

1. 分层检测策略：根据风险等级配置不同的检测器和阈值
2. 性能权衡：避免配置过多的高开销检测器
3. 持续迭代：定期审查检测结果，优化检测规则

安全加固建议

错误处理与降级

护栏系统实现了完善的错误处理机制，确保在异常情况下应用仍能正常运行。

异常类型

降级策略配置

guardrails = GuardrailsManager(
    project_name="my_app",
    detector_config=[...],
    fallback_config={
        "on_detection_error": "allow",  # 检测异常时默认放行
        "on_timeout": "allow",           # 超时时默认放行
        "on_quota_exceeded": "block",   # 配额超限默认拦截
        "log_fallbacks": True            # 记录降级事件
    }
)

相关功能模块

安全护栏管理与RagaAI Catalyst的其他核心功能紧密集成。

graph LR
    A[安全护栏管理] --> B[项目管理]
    A --> C[数据集管理]
    A --> D[追踪系统]
    A --> E[评估框架]
    B --> F[统一认证]
    C --> F
    D --> F
    E --> F

• 项目管理：护栏配置作为项目元数据进行管理
• 数据集管理：安全测试数据集用于验证护栏效果
• 追踪系统：记录护栏执行事件用于审计分析
• 评估框架：评估护栏的检出率和误报率

资料来源：README.md:1-50

总结

RagaAI Catalyst的安全护栏管理模块提供了一套完整、可扩展的安全保护解决方案。通过内置检测器与自定义检测器的组合，以及灵活的策略配置机制，开发者能够快速为AI应用构建坚实的安全防线。该模块与RagaAI Catalyst平台的认证系统、项目管理和追踪功能深度集成，为企业级AI应用提供了全方位的安全保障能力。

Pitfall Log / 踩坑日志

项目：raga-ai-hub/RagaAI-Catalyst

摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：2.1.7.1。

1. 安装坑 · 来源证据：2.1.7.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：2.1.7.1
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2b18c29bfc6747c28b5639af6516ba77 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.1.7.1 | 来源类型 github_release 暴露的待验证使用条件。

2. 安装坑 · 来源证据：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Question / suggestion: using WFGY Problem Map as a 16-mode RAG failure taxonomy
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_dd2f7b1bb49d46a99df2c7a41ee49e84 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/250 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：Standardizing Agent Commerce: Merxex Integration Proposal

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Standardizing Agent Commerce: Merxex Integration Proposal
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9481b029aa184751bae8e274727f7cbc | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/264 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | README/documentation is current enough for a first validation pass.

5. 运行坑 · 来源证据：2.1.6

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.1.6
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0ed1a94dca0f4475945471f26748538c | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6 | 来源类型 github_release 暴露的待验证使用条件。

6. 运行坑 · 来源证据：2.2.3

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.2.3
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_3c04cea2aa1a4d4d9f6563d2b5174e57 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.3 | 来源类型 github_release 暴露的待验证使用条件。

7. 运行坑 · 来源证据：2.2.4

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：2.2.4
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6164e251affd4b40885ba64b8f7cccc3 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.4 | 来源类型 github_release 暴露的待验证使用条件。

8. 运行坑 · 来源证据：v2.1.5

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v2.1.5
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_09e7b33dcd60462f9e6ad53326782e9c | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.5 | 来源类型 github_release 暴露的待验证使用条件。

9. 维护坑 · 来源证据：Integration: Agent-SRE Reliability Layer for AI Agent Monitoring

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Integration: Agent-SRE Reliability Layer for AI Agent Monitoring
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4a186da805644f91915f241bdba8ce27 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/253 | 来源类型 github_issue 暴露的待验证使用条件。

10. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | last_activity_observed missing

11. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | no_demo; severity=medium

12. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | No sandbox install has been executed yet; downstream must verify before user use.

13. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | no_demo; severity=medium

14. 安全/权限坑 · 来源证据：2.1.6.2

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.1.6.2
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_daf5807f609141008dc6aaadbc15d774 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.2 | 来源类型 github_release 暴露的待验证使用条件。

15. 安全/权限坑 · 来源证据：2.1.6.4

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.1.6.4
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0790ea07d026457a8eb6bf9e454fdcfa | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/2.1.6.4 | 来源类型 github_release 暴露的待验证使用条件。

16. 安全/权限坑 · 来源证据：2.2.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：2.2.1
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f1b8373166c14c4dba527f91193c93f1 | https://github.com/raga-ai-hub/RagaAI-Catalyst/releases/tag/v2.2.1 | 来源类型 github_release 暴露的待验证使用条件。

17. 安全/权限坑 · 来源证据：Authorization receipts for agent traces — signed governance proof per traced action

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Authorization receipts for agent traces — signed governance proof per traced action
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f70b1d74d8064a45bd97566d464f6f0e | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/263 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

18. 安全/权限坑 · 来源证据：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_534211e56e854a00af1a687847a67d77 | https://github.com/raga-ai-hub/RagaAI-Catalyst/issues/256 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

19. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | issue_or_pr_quality=unknown

20. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:847717439 | https://github.com/raga-ai-hub/RagaAI-Catalyst | release_recency=unknown