Mage-AI 项目中的运行时变量使用指南

Mage-AI 项目中的运行时变量使用指南

mage-ai MAGE AI是一个专注于模型生命周期管理的平台，它有助于简化机器学习模型从训练到部署的过程，提供版本控制、协作、API服务化等功能，提高AI团队的工作效率。 项目地址: https://gitcode.com/gh_mirrors/ma/mage-ai

什么是运行时变量

运行时变量是 Mage-AI 数据管道中的一个重要特性，它允许开发者在管道执行过程中动态传递和使用全局变量。这些变量可以在管道的任何代码块中访问，非常适合存储需要在多个块之间共享的常量或配置参数。

运行时变量的核心价值在于：

• 提高代码复用性：避免在多个地方硬编码相同的值
• 增强灵活性：允许在不修改代码的情况下调整参数
• 支持环境隔离：可以为不同环境配置不同的变量值

运行时变量的基本使用

变量类型支持

Mage-AI 支持以下 Python 基本类型作为运行时变量：

• 基本类型：整数、字符串、浮点数、布尔值
• 容器类型：列表、字典、集合

变量命名必须符合 Python 标识符规范：

• 不能包含空格
• 不能以数字开头
• 避免使用 Python 关键字

在代码块中访问变量

运行时变量通过 **kwargs 参数传递给代码块函数：

from pandas import DataFrame
from mage_ai.data_preparation.decorators import data_loader

@data_loader
def load_data(**kwargs) -> DataFrame:
    # 获取运行时变量
    file_path = kwargs.get('data_file_path')
    max_rows = kwargs.get('max_rows', 1000)  # 带默认值
    
    # 使用变量加载数据
    return pd.read_csv(file_path, nrows=max_rows)

创建运行时变量的方法

1. 通过 Mage UI 界面创建

在 Mage 编辑器的侧边栏中找到"Variables"标签页：

1. 点击"New"按钮创建新变量
2. 输入变量名称和值
3. 按 Enter 保存

编辑现有变量：

1. 将鼠标悬停在变量上
2. 点击编辑按钮
3. 修改名称或值后按 Enter 保存

2. 通过 YAML 配置文件创建

可以在管道的 metadata.yaml 文件中定义变量，支持环境特定的配置：

variables:
   database_url: "postgres://user:pass@localhost/db"
   batch_size: 1000
   dev:
      api_endpoint: "https://dev.api.example.com"
   staging:
      api_endpoint: "https://staging.api.example.com"
   prod:
      api_endpoint: "https://api.example.com"

3. 通过 Python 代码设置

可以在代码中动态设置全局变量：

from mage_ai.data_preparation.variable_manager import set_global_variable

# 设置全局变量
set_global_variable('pipeline_uuid', 'api_key', 'your-api-key-here')

默认运行时变量

Mage-AI 提供了一些内置的运行时变量：

• execution_date: 管道执行的日期时间对象
• event: 如果管道由事件触发，包含事件负载

运行带变量的管道

命令行方式运行

安装 Mage-AI 后，可以使用以下命令运行管道并传递变量：

mage run project_path pipeline_uuid --runtime-vars '{"var1": "value1", "var2": 42}'

Python 脚本方式运行

在 Python 脚本中运行管道并传递变量：

import mage_ai

mage_ai.run(
    'your_pipeline', 
    'repos/your_repo',
    start_date='2023-01-01',
    end_date='2023-01-31',
    threshold=0.95
)

实际应用案例

案例1：每日日志分析

假设我们需要分析每日应用日志，统计各类日志的数量分布：

1. 数据加载块 - 使用日期变量加载特定日期的日志：

@data_loader
def load_daily_logs(**kwargs):
    log_date = kwargs['log_date']
    log_dir = kwargs['log_dir']
    # 加载指定日期的日志文件
    ...

2. 转换块 - 统计日志类型分布：

@transformer
def log_stats(df: DataFrame, **kwargs):
    log_date = kwargs['log_date']
    stats = df['type'].value_counts()
    return pd.DataFrame({log_date: stats}).T

运行管道时动态指定日期：

mage_ai.run('log_analysis', log_date='2023-07-15', log_dir='/var/log/app')

案例2：模型火箭数据分析

处理模型火箭发射数据时，可能需要不同的单位转换：

@transformer
def convert_units(df: DataFrame, **kwargs):
    # 使用运行时变量进行单位转换
    angle_conversion = kwargs.get('deg_to_rad', 0.0174533)  # 默认值
    velocity_conversion = kwargs.get('mps_to_kph', 3.6)
    
    df['angle_rad'] = df['angle_deg'] * angle_conversion
    df['velocity_kph'] = df['velocity_mps'] * velocity_conversion
    return df

这样可以在运行时灵活指定转换系数：

# 使用默认转换系数
mage_ai.run('rocket_analysis')

# 或者指定自定义系数
mage_ai.run('rocket_analysis', deg_to_rad=0.017453292519943, mps_to_kph=3.6)

最佳实践建议

1. 命名规范：使用有意义的变量名，如 api_timeout_sec 而非简单的 timeout

2. 默认值：在代码中为关键变量提供合理的默认值

3. 文档记录：在管道文档中记录所有使用的运行时变量及其预期类型

4. 环境隔离：利用 YAML 配置为不同环境设置不同的变量值

5. 敏感信息：避免将密码等敏感信息直接作为变量值，考虑使用秘钥管理系统

运行时变量是 Mage-AI 中实现灵活、可配置数据管道的重要工具，合理使用可以大大提高管道的复用性和可维护性。

mage-ai MAGE AI是一个专注于模型生命周期管理的平台，它有助于简化机器学习模型从训练到部署的过程，提供版本控制、协作、API服务化等功能，提高AI团队的工作效率。 项目地址: https://gitcode.com/gh_mirrors/ma/mage-ai