配置参考 – DBHOO

版本: dbhoo-lpu v1.0.1 (Open Source)
最后更新: 2026-07-20

1. 概述

dbhoo-lpu提供了多层次的配置选项，从编译期选项到运行时配置，以适应不同的部署场景和性能需求。

配置分为以下几类：

编译选项: 通过 CMake 或编译宏设置，编译时生效
运行时配置: 通过 API 函数在运行时设置
限制常量: 定义算法层的上界和默认值
状态码: 统一的错误码定义

2. 编译选项

2.1 CMake 选项

选项	默认值	类型	说明
`CMAKE_BUILD_TYPE`	`Release`	STRING	构建类型: `Debug`, `Release`, `RelWithDebInfo`, `MinSizeRel`
`CMAKE_INSTALL_PREFIX`	`/usr/local`	PATH	安装路径
`LPU_BUILD_TESTS`	`ON`	BOOL	是否构建测试套件
`LPU_BUILD_SHARED`	`ON`	BOOL	是否构建共享库 (.so/.dll/.dylib)
`LPU_BUILD_STATIC`	`ON`	BOOL	是否构建静态库 (.a/.lib)
`LPU_WITH_CUDA`	`OFF`	BOOL	是否启用 CUDA 支持（商业版）
`LPU_WITH_PLUGIN`	`ON`	BOOL	是否启用插件系统
`LPU_ENABLE_SAFETY`	`ON`	BOOL	是否启用安全检查

2.2 使用示例

# 最小化构建（仅静态库，无测试）
cmake .. \
    -DCMAKE_BUILD_TYPE=Release \
    -DLPU_BUILD_TESTS=OFF \
    -DLPU_BUILD_SHARED=OFF \
    -DLPU_BUILD_STATIC=ON

# Debug 构建（含调试信息）
cmake .. \
    -DCMAKE_BUILD_TYPE=Debug \
    -DLPU_BUILD_TESTS=ON

# 自定义安装路径
cmake .. -DCMAKE_INSTALL_PREFIX=/opt/lpu

2.3 编译宏定义

宏	说明	位置
`DBHOO_LPU_EDITION`	版本类型 (0=开源, 1=商业)	`lpu_version_info.h`
`LPU_WITH_CUDA`	编译时启用 CUDA	编译选项
`LPU_LIMIT_MHA_MAX_SEQ`	MHA 最大序列长度上限	`lpu_limits.h`
`LPU_LIMIT_LOGITS_CAP`	Logits 处理上限	`lpu_limits.h`
`LPU_LIMIT_MOE_FFN_DH`	MoE FFN hidden 上限	`lpu_limits.h`

3. 运行时配置

3.1 设备管理配置

设备管理相关函数定义在 lpu_device.h 中。

设备偏好

typedef enum lpu_device_preference_e {
  LPU_DEV_PREF_CPU = 0U,       // 强制使用 CPU
  LPU_DEV_PREF_GPU_CUDA = 1U,  // 优先使用 CUDA GPU（不可用则回退）
  LPU_DEV_PREF_AUTO = 2U       // 自动选择（根据规模和功耗策略）
} lpu_device_preference_t;

设置和获取：

void lpu_device_set_preference(lpu_device_preference_t pref);
lpu_device_preference_t lpu_device_get_preference(void);

功耗策略

typedef enum lpu_device_power_e {
  LPU_DEV_POWER_BALANCED = 0U,    // 平衡模式
  LPU_DEV_POWER_LOW = 1U,         // 低功耗模式（禁用 GPU）
  LPU_DEV_POWER_PERFORMANCE = 2U  // 高性能模式（倾向 GPU）
} lpu_device_power_t;

设置和获取：

void lpu_device_set_power(lpu_device_power_t power);
lpu_device_power_t lpu_device_get_power(void);

部署形态

typedef enum lpu_deployment_e {
  LPU_DEPLOYMENT_EDGE = 0U,   // 端侧部署（保守使用 GPU）
  LPU_DEPLOYMENT_CLOUD = 1U   // 云侧部署（激进使用 GPU）
} lpu_deployment_t;

设置和获取：

void lpu_device_set_deployment(lpu_deployment_t dep);
lpu_deployment_t lpu_device_get_deployment(void);

CUDA 设备选择

void lpu_device_set_cuda_device(int device_index);
int lpu_device_get_cuda_device(void);

运行时配置应用

一次性应用所有配置：

void lpu_device_apply_runtime_config(
    uint32_t deployment,        // 0=EDGE, 1=CLOUD
    uint32_t device_preference, // 0=CPU, 1=GPU_CUDA, 2=AUTO
    uint32_t power_mode         // 0=BALANCED, 1=LOW, 2=PERFORMANCE
);

设备查询

// 初始化设备探测（幂等，可多次调用）
void lpu_device_init(void);

// CUDA 是否可用
int lpu_device_cuda_available(void);

// ARM 架构是否可用
int lpu_device_arm_available(void);

// RISC-V 架构是否可用
int lpu_device_riscv_available(void);

// AMD GPU 是否可用
int lpu_device_amd_gpu_available(void);

// Intel GPU 是否可用
int lpu_device_intel_gpu_available(void);

GEMM 设备决策

// 判断指定大小的 GEMM 是否应该使用 GPU
int lpu_device_want_gpu_for_gemm_size(size_t m, size_t k, size_t n);

// 获取 GEMM 的有效设备
lpu_device_effective_t lpu_device_effective_gemm(size_t m, size_t k, size_t n);

3.2 GEMM 配置

GEMM 分块参数通过函数参数配置：

lpu_status lpu_gemm_f32(
    const float *a,
    const float *b,
    float *c,
    size_t m,
    size_t k,
    size_t n,
    size_t bm,    // M 分块大小 (0 = 使用默认值)
    size_t bk,    // K 分块大小 (0 = 使用默认值)
    size_t bn     // N 分块大小 (0 = 使用默认值)
);

分块参数选择指南:

设为 0 时使用内置默认值，适合大多数情况
对于特定硬件，可以调整分块大小优化缓存命中率
典型值: bm=64~256, bk=64~256, bn=64~256
分块过大可能导致缓存不足，过小可能增加开销

3.3 注意力配置

typedef struct lpu_mha_config {
  uint32_t num_heads;           // 查询头数
  uint32_t head_dim;            // 头维度
  uint32_t num_kv_heads;        // KV 头数 (GQA)
  uint32_t max_seq;             // 最大序列长度
  lpu_dtype_t qkv_dtype;        // QKV 数据类型
  lpu_dtype_t acc_dtype;        // 累加数据类型
  uint32_t flags;               // 标志位
  float causal_mask_value;      // 因果掩码值
  uint32_t sliding_window;      // 滑动窗口大小
} lpu_mha_config_t;

标志位定义

#define LPU_MHA_FLAG_CAUSAL 1U   // 启用因果掩码

支持检查

lpu_status lpu_mha_check_supported(
    const lpu_mha_config_t *cfg,
    char *reason_out,           // 不支持的原因输出
    size_t reason_cap           // 缓冲区大小
);

3.4 KV Cache 配置

typedef struct lpu_kvcache_desc {
  uint32_t num_layers;          // 层数
  uint32_t num_heads;           // 头数（含义取决于 num_kv_heads）
  uint32_t num_kv_heads;        // KV 头数 (0 = 不启用 GQA 解释)
  uint32_t head_dim;            // 头维度
  uint32_t max_seq;             // 最大序列长度
  lpu_dtype_t dtype;            // 数据类型
} lpu_kvcache_desc_t;

内存需求计算

lpu_status lpu_kvcache_bytes(
    const lpu_kvcache_desc_t *d,
    size_t *out_bytes           // 输出所需字节数
);

计算公式（F32）:

总字节数 = num_layers * 2 * max_seq * num_kv_heads * head_dim * 4

3.5 采样配置

采样配置通过函数参数传递：

lpu_status lpu_sample_topk_topp_f32(
    const float *logits,
    size_t vocab_size,
    uint32_t top_k,             // Top-K 值 (0 = 禁用)
    float top_p,                // Top-P 值 (0 = 禁用)
    float temperature,          // 温度系数 (> 0)
    uint32_t seed,              // 随机种子
    uint32_t *out_token,
    float *out_prob
);

典型配置:

场景	temperature	top_k	top_p	说明
确定性输出	0.0 / 接近 0	–	–	Greedy 采样
创意写作	0.7 ~ 1.0	50	0.9	平衡质量和多样性
高多样性	1.0 ~ 1.5	100	0.95	更随机的输出
代码生成	0.2 ~ 0.7	10	0.95	更精确的输出

4. 设备配置

4.1 设备配置组合

以下是一些典型的设备配置组合：

配置 1: 纯 CPU（低功耗/端侧）

lpu_device_set_deployment(LPU_DEPLOYMENT_EDGE);
lpu_device_set_preference(LPU_DEV_PREF_CPU);
lpu_device_set_power(LPU_DEV_POWER_LOW);

适用场景：

嵌入式设备
电池供电设备
对功耗敏感的场景

配置 2: 自动选择（平衡）

lpu_device_set_deployment(LPU_DEPLOYMENT_EDGE);
lpu_device_set_preference(LPU_DEV_PREF_AUTO);
lpu_device_set_power(LPU_DEV_POWER_BALANCED);

适用场景：

通用桌面端
兼顾性能和功耗

配置 3: 高性能（云侧）

lpu_device_set_deployment(LPU_DEPLOYMENT_CLOUD);
lpu_device_set_preference(LPU_DEV_PREF_AUTO);
lpu_device_set_power(LPU_DEV_POWER_PERFORMANCE);

适用场景：

服务器部署
高吞吐推理服务

配置 4: 强制 GPU

lpu_device_set_preference(LPU_DEV_PREF_GPU_CUDA);
lpu_device_set_power(LPU_DEV_POWER_PERFORMANCE);

适用场景：

已知有 GPU 且确定需要 GPU 加速
性能基准测试

注意: 开源版仅支持 CPU，GPU 支持需要 LPU 商业版。以上配置 API 在开源版中可用，但实际执行始终回退到 CPU。

5. 数据类型配置

5.1 数据类型枚举

typedef enum lpu_dtype {
  LPU_DTYPE_F32 = 0,    // 单精度浮点 (32-bit)
  LPU_DTYPE_F16 = 1,    // 半精度浮点 (16-bit)
  LPU_DTYPE_I8  = 2,    // 8 位有符号整数
  LPU_DTYPE_I4  = 3,    // 4 位整数
  LPU_DTYPE_FP8 = 4,    // 8 位浮点
} lpu_dtype_t;

5.2 数据类型大小查询

lpu_status lpu_dtype_size_bytes(lpu_dtype_t dt, uint32_t *out_bytes);

各类型大小：

类型	字节数	位宽	开源版支持
`LPU_DTYPE_F32`	4	32	✅
`LPU_DTYPE_F16`	2	16	❌
`LPU_DTYPE_I8`	1	8	❌
`LPU_DTYPE_I4`	0.5	4	❌
`LPU_DTYPE_FP8`	1	8	❌

注意: I4 类型按 2 个元素打包为 1 字节计步长，lpu_dtype_size_bytes 返回的是对齐粒度参考值。

6. 限制常量

限制常量定义在 lpu_limits.h 中：

// MHA / SDPA 最大序列长度上限
#define LPU_LIMIT_MHA_MAX_SEQ 512U

// 采样 / Logits 处理上限（top-k/top-p 内部排序数组大小等）
#define LPU_LIMIT_LOGITS_CAP 256U

// MoE FFN hidden 维度上限（参考实现）
#define LPU_LIMIT_MOE_FFN_DH 512U

6.1 注意力最大序列长度

#define LPU_MHA_SDPA_F32_MAX_SEQ 8192U   // F32 SDPA 最大序列长度

注意: LPU_LIMIT_MHA_MAX_SEQ 是算法层统一上界，LPU_MHA_SDPA_F32_MAX_SEQ 是 F32 SDPA 的具体上限。实际可支持的序列长度还受限于内存和计算资源。

6.2 调整限制

如需调整限制，修改 lpu_limits.h 中的宏定义后重新编译即可。调整时需注意：

增大限制可能增加内存使用
过小的限制可能导致功能受限
建议根据实际部署场景调整

7. 状态码

所有 dbhoo-lpu函数返回统一的状态码，定义在 lpu_status.h 中：

typedef int lpu_status;

#define LPU_OK              0     // 成功
#define LPU_ERR_NULL        (-1)  // NULL 指针错误
#define LPU_ERR_INVALID_ARG (-2)  // 无效参数
#define LPU_ERR_ALIGN       (-3)  // 对齐错误
#define LPU_ERR_UNSUPPORTED (-4)  // 不支持的操作
#define LPU_ERR_RANGE       (-5)  // 范围错误（溢出、越界等）
#define LPU_ERR_NO_MEM      (-6)  // 内存不足
#define LPU_ERR_DEVICE      (-7)  // 设备错误（GPU 不可用等）

7.1 状态码表

状态码	值	含义	常见原因
`LPU_OK`	0	成功	操作正常完成
`LPU_ERR_NULL`	-1	NULL 指针	输入指针为 NULL
`LPU_ERR_INVALID_ARG`	-2	无效参数	参数值非法（如负数维度）
`LPU_ERR_ALIGN`	-3	对齐错误	内存地址未按要求对齐
`LPU_ERR_UNSUPPORTED`	-4	不支持	请求的功能/配置不支持
`LPU_ERR_RANGE`	-5	范围错误	溢出、越界、数值非有限等
`LPU_ERR_NO_MEM`	-6	内存不足	内存分配失败
`LPU_ERR_DEVICE`	-7	设备错误	GPU 不可用或策略禁止

7.2 错误检查模式

推荐的错误检查模式：

lpu_status status = lpu_some_function(...);
if (status != LPU_OK) {
    // 处理错误
    fprintf(stderr, "Error: %d\n", status);
    return status;
}

8. 插件配置

注意: 插件系统 API 在开源版中定义，但主要扩展功能需商业版插件。本章节介绍配置接口。

8.1 插件类型

typedef enum lpu_plugin_type_e {
    LPU_PLUGIN_TYPE_UNKNOWN = 0,
    LPU_PLUGIN_TYPE_GEMM = 1,
    LPU_PLUGIN_TYPE_ATTENTION = 2,
    LPU_PLUGIN_TYPE_QUANT = 3,
    LPU_PLUGIN_TYPE_KVCACHE = 4,
    LPU_PLUGIN_TYPE_SAMPLING = 5,
    LPU_PLUGIN_TYPE_AUTOTUNE = 6,
    LPU_PLUGIN_TYPE_GRAPH_OPT = 7,
    LPU_PLUGIN_TYPE_OFFLOAD = 8,
    LPU_PLUGIN_TYPE_COMPRESSION = 9,
    LPU_PLUGIN_TYPE_OBSERVABILITY = 10,
    LPU_PLUGIN_TYPE_CUDA = 11,
    LPU_PLUGIN_TYPE_COLLECTIVE = 12,
    LPU_PLUGIN_TYPE_MOE = 13,
    LPU_PLUGIN_TYPE_VISION = 14,
    LPU_PLUGIN_TYPE_SECURITY = 15,
    LPU_PLUGIN_TYPE_CUSTOM = 255
} lpu_plugin_type_t;

8.2 插件许可证类型

typedef enum lpu_plugin_license_type_e {
    LPU_PLUGIN_LICENSE_OPEN_SOURCE = 0,
    LPU_PLUGIN_LICENSE_COMMERCIAL = 1
} lpu_plugin_license_type_t;

8.3 插件管理器 API

// 初始化插件管理器
lpu_status lpu_plugin_manager_init(void);

// 关闭插件管理器
lpu_status lpu_plugin_manager_shutdown(void);

// 加载插件
lpu_status lpu_plugin_load(const char* path, lpu_plugin_handle_t* out_handle);

// 卸载插件
lpu_status lpu_plugin_unload(lpu_plugin_handle_t handle);

// 获取插件信息
lpu_status lpu_plugin_get_info(lpu_plugin_handle_t handle, lpu_plugin_info_t* info);

// 列出所有已加载插件
lpu_status lpu_plugin_list(lpu_plugin_handle_t* handles, size_t* count);

// 按类型查找插件
lpu_status lpu_plugin_find_by_type(
    lpu_plugin_type_t type,
    lpu_plugin_handle_t* handles,
    size_t* count);

// 按许可证查找插件
lpu_status lpu_plugin_find_by_license(
    lpu_plugin_license_type_t license_type,
    lpu_plugin_handle_t* handles,
    size_t* count);

// 检查某类型插件是否已加载
lpu_status lpu_plugin_is_loaded(lpu_plugin_type_t type, bool* is_loaded);

目录

1. 概述

2. 编译选项

2.1 CMake 选项

2.2 使用示例

2.3 编译宏定义

3. 运行时配置

3.1 设备管理配置

设备偏好

功耗策略

部署形态

CUDA 设备选择

运行时配置应用

设备查询

GEMM 设备决策

3.2 GEMM 配置

3.3 注意力配置

标志位定义

支持检查

3.4 KV Cache 配置

内存需求计算

3.5 采样配置

4. 设备配置

4.1 设备配置组合

配置 1: 纯 CPU（低功耗/端侧）

配置 2: 自动选择（平衡）

配置 3: 高性能（云侧）

配置 4: 强制 GPU

5. 数据类型配置

5.1 数据类型枚举

5.2 数据类型大小查询

6. 限制常量

6.1 注意力最大序列长度

6.2 调整限制

7. 状态码

7.1 状态码表

7.2 错误检查模式

8. 插件配置

8.1 插件类型

8.2 插件许可证类型

8.3 插件管理器 API