isagellm-backend 0.1.0

sageLLM backend provider abstraction and mock implementation

sagellm-backend

BackendProvider 抽象与内置 mock 实现。

• 仓库名：sagellm-backend
• PyPI 包名：isagellm-backend
• import 名：sagellm_backend

架构层级

Level 0: sagellm-protocol (最基础，无依赖)
    ↓
Level 1: sagellm-backend (依赖 protocol) ← 当前包
    ↓
Level 2: sagellm-core (依赖 protocol + backend)
    ↓
Level 3: 功能模块（依赖 protocol + backend + core）

依赖说明：

• ✅ 生产依赖：isagellm-protocol (仅依赖 protocol)
• ✅ 开发依赖：isagellm-core (仅用于测试 entry point 机制)
• ❌ 不依赖：sagellm-core 的任何运行时功能

Entry Points

• group：sagellm.backends
• 内置 kind：mock

其他硬件后端（ascend_cann/cuda 等）可通过独立插件包扩展，或在本仓库内添加 provider。

组件说明

BackendProvider 抽象

• 定义统一的硬件抽象接口
• 覆盖：stream/event、集合通信、KV 块管理、kernel 注册
• 能力矩阵驱动（CapabilityDescriptor）

Mock 实现

• 支持 CI 测试（无需真实硬件）
• 能力矩阵可配置（模拟不同后端能力）
• Fail-fast 错误处理

安装

pip install isagellm-backend

开发模式：

git clone https://github.com/intellistream/sagellm-backend.git
cd sagellm-backend
pip install -e ".[dev]"

# 安装 pre-commit hooks（强烈推荐）
pre-commit install

开发者指南

本项目使用完整的代码质量保障机制：

• ✅ Pre-commit hooks: 自动格式化和 lint
• ✅ Unit tests: 17 个单元测试 + 集成测试
• ✅ CI/CD: GitHub Actions 自动化测试
• ✅ Type checking: 100% 类型注解覆盖

详见 CONTRIBUTING.md。

使用示例

from sagellm_backend import MockBackendProvider, DType

# 创建 mock backend
backend = MockBackendProvider(
    supported_dtypes=[DType.FP16, DType.BF16],
    has_collective=True,
)

# 查询能力
cap = backend.capability()
print(cap.supported_dtypes)

# 分配 KV 块
block = backend.kv_block_alloc(128, DType.FP16)

扩展新后端

# 在 providers/ 下创建新模块
class AscendBackendProvider:
    def capability(self) -> CapabilityDescriptor:
        return CapabilityDescriptor(
            supported_dtypes=[DType.FP16, DType.BF16, DType.INT8],
            # ...
        )

    # 实现其他接口...

# 注册 entry point (pyproject.toml)
[project.entry-points."sagellm.backends"]
ascend_cann = "sagellm_backend.providers.ascend:create_ascend_backend"