isagellm-core 0.5.4.26

sageLLM core runtime with PD separation (MVP)

sagellm-core

sageLLM Core 是一个硬件无关的 LLM 推理引擎，提供统一的推理接口（generate、stream、execute），支持自动后端选择（CPU/CUDA/Ascend），内置解码策略系统，并支持 PD 分离的混合模式执行。

版本: 0.4.0.17 | 最后更新: 2026-02-02 | 协议遵循: Protocol v0.1

📍 职责定位

在整个 sageLLM 架构中的位置与职责：

┌─────────────────────────────────────────────────────────────┐
│                  Application Layer                          │
│        (sagellm-gateway, sagellm-control-plane)             │
└────────────────┬────────────────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────────────────┐
│  sagellm-core 本仓库                                         │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  LLMEngine: 硬件无关的统一推理入口                    │   │
│  │  • generate() / stream() / execute()                 │   │
│  │  • 自动后端选择 (cpu/cuda/ascend)                    │   │
│  │  • Continuous Batching 调度                         │   │
│  │  • 解码策略系统 (Greedy/Sampling/BeamSearch)        │   │
│  │  • PD 分离混合模式执行                               │   │
│  └──────────────────────────────────────────────────────┘   │
├──────────────────────────────────────────────────────────────┤
│  核心依赖 (L1 层)                                            │
│  ├─ sagellm-backend: 硬件抽象、设备管理                    │
│  ├─ sagellm-comm: 通信硬件、TP/PP 通信                     │
│  ├─ sagellm-kv-cache: KV 缓存管理、驱逐策略              │
│  └─ sagellm-protocol: 数据结构、错误定义                  │
└──────────────────────────────────────────────────────────────┘

职责边界：

• ✅ Core 负责: LLMEngine、调度、推理编排、解码策略
• ✅ Backend 负责: 硬件抽象、设备管理、算子/内核
• ✅ Comm 负责: 通信硬件抽象、集合操作、拓扑管理
• ✅ Protocol 负责: 全局共享的数据结构、错误码、ID 方案

性能主路径边界

国产硬件性能优化的正式执行链是：scheduler -> executor -> worker -> model_runner -> backend attention/kernel。

• shared stream 只能作为 admission、telemetry、event fan-out 层，不能长期拥有独立 decode 语义。
• batch_type、block_tables、slot_mapping、context_lens 必须从 scheduler 贯穿到执行层。
• vLLM 或 HuggingFace fallback 不是 sagellm-core 的长期性能方向。

规范说明见：https://github.com/intellistream/sagellm-docs/blob/main/docs/specs/performance_mainline_architecture.md

✨ 核心特性

特性	说明
统一推理接口	generate() / stream() / execute() - 同步、流式、协议兼容
硬件无关	CPU/CUDA/Ascend - 自动检测与选择
解码策略系统	Greedy、Sampling、Beam Search、Contrastive Decoding
Continuous Batching	动态批处理，充分利用硬件
PD 分离执行	Prefill 和 Decode 阶段分离，支持混合模式
配置驱动	YAML/JSON 配置，Pydantic v2 验证
HTTP Server	FastAPI 实现，支持 SSE 流式传输
CPU-First	完整支持无 GPU 环境，便于测试开发
类型安全	完整的 Python 类型标注，Mypy 支持

📦 依赖关系

核心依赖（自动安装）

isagellm-protocol>=0.4.0.0,<0.5.0  # 协议定义
isagellm-backend>=0.4.0.0,<0.5.0   # 硬件抽象
isagellm-comm>=0.4.0.0,<0.5.0      # 通信后端
isagellm-kv-cache>=0.4.0.0,<0.5.0  # KV 缓存管理

# 框架依赖
pydantic>=2.0.0      # 数据验证
pyyaml>=6.0.0        # 配置解析
torch>=2.0.0         # 张量计算
transformers>=4.35.0 # 模型加载
fastapi>=0.100.0     # HTTP 服务

谁依赖我

• 🔵 sagellm-control-plane: 使用 Core 进行请求调度、负载均衡
• 🟡 sagellm-compression: 建立在 Core 的模型执行层上
• 🟢 sagellm-gateway: 提供 OpenAI 兼容 API

🚀 安装指南

PyPI 安装（推荐）

# 安装最新版本
pip install isagellm-core==0.4.0.17

# 安装指定版本范围
pip install "isagellm-core>=0.4.0.0,<0.5.0"

本地开发安装

# 克隆仓库
git clone https://github.com/intellistream/sagellm-core.git
cd sagellm-core

# 方式 1：一键安装（推荐）
# 默认等价于 --dev
./quickstart.sh

# 标准模式（稳定/发布导向）：依赖优先来自 PyPI
./quickstart.sh --standard

# 开发模式（联调导向）：先安装 PyPI，再尽量用本地 sibling 仓库 editable 覆盖
./quickstart.sh --dev

# 查看帮助
./quickstart.sh --help

quickstart.sh 当前语义：

• --standard：安装 PyPI 基线依赖 + 当前仓库 editable 安装
• --dev：在 --standard 基础上，对本地存在的 sagellm-protocol / sagellm-backend / sagellm-comm / sagellm-kv-cache 执行 pip install -e <repo> --no-deps 覆盖
• 安装前会动态清理已安装的 isagellm-* 包（可用 --skip-cleanup 跳过）
• 失败时会输出详细诊断日志，便于定位安装问题

本地链接依赖（用于本地多包开发）

# 如果同时在开发 backend/protocol/comm，使用本地版本
pip install -e ../sagellm-protocol
pip install -e ../sagellm-backend  
pip install -e ../sagellm-comm
pip install -e ../sagellm-kv-cache
pip install -e ".[dev]"

验证安装

# 检查 package 版本
python -c "import sagellm_core; print(sagellm_core.__version__)"

# 运行快速测试
pytest tests/test_ci_smoke.py -v

🎯 快速开始

1. 基础推理

from sagellm_core import LLMEngine, LLMEngineConfig

# 创建配置
config = LLMEngineConfig(
    model_path="sshleifer/tiny-gpt2",  # HuggingFace 模型名或本地路径
    backend_type="cpu",  # 自动选择 cpu/cuda/ascend
    max_new_tokens=20
)

# 初始化引擎
engine = LLMEngine(config)

# 异步运行
import asyncio

async def main():
    await engine.start()

    # 同步生成（完整输出）
    response = await engine.generate("Hello, world!")
    print(response.output_text)

    # 流式生成（逐 token 返回）
    async for event in engine.stream("Once upon a time"):
        if event.event == "delta":
            print(event.chunk, end="", flush=True)

    await engine.stop()

asyncio.run(main())

2. 使用采样参数控制生成

from sagellm_core import LLMEngine, LLMEngineConfig
from sagellm_protocol.sampling import SamplingParams, DecodingStrategy

async def main():
    config = LLMEngineConfig(model_path="sshleifer/tiny-gpt2")
    engine = LLMEngine(config)
    await engine.start()

    prompt = "The future of AI is"

    # 确定性输出（Greedy）
    response = await engine.generate(
        prompt,
        sampling_params=SamplingParams(
            strategy=DecodingStrategy.GREEDY,
            max_tokens=20
        )
    )
    print(f"Greedy: {response.output_text}")

    # 随机采样（Temperature 控制）
    response = await engine.generate(
        prompt,
        sampling_params=SamplingParams(
            strategy=DecodingStrategy.SAMPLING,
            temperature=0.7,
            top_p=0.9,
            max_tokens=20
        )
    )
    print(f"Sampling: {response.output_text}")

    await engine.stop()

asyncio.run(main())

3. 从 YAML 配置文件运行 Demo

# 查看可用配置
cat examples/config_cpu.yaml

# 运行 Demo
python -m sagellm_core.demo --config examples/config_cpu.yaml --verbose

# 查看输出 metrics
cat metrics.json

4. 启动 HTTP Server

# 方式 1：命令行
sage-engine --host 0.0.0.0 --port 8000

# 方式 2：Python API
from sagellm_core import engine_server_app
import uvicorn

uvicorn.run(engine_server_app, host="0.0.0.0", port=8000)

5. HTTP 请求示例

# 同步推理
curl -X POST http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt2",
    "prompt": "Hello",
    "max_tokens": 20
  }'

# 流式推理
curl -X POST http://localhost:8000/v1/completions/stream \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt2",
    "prompt": "Hello",
    "max_tokens": 20,
    "stream": true
  }'

📚 API 文档

LLMEngine - 主入口

初始化:

LLMEngineConfig(
    model_path: str,                # 必需：HuggingFace 名或本地路径
    backend_type: str = "auto",     # 计算后端：cpu/cuda/ascend/auto
    comm_type: str = "auto",        # 通信后端：gloo/nccl/hccl/auto
    max_batch_size: int = 32,       # 最大批大小
    max_model_len: int = 4096,      # 最大序列长度
    max_new_tokens: int = 128,      # 每个请求最多生成 token 数
    tensor_parallel_size: int = 1,  # 张量并行度
    pipeline_parallel_size: int = 1, # 流水线并行度
    dtype: str = "auto",             # 数据类型：float32/float16/bfloat16
)

关键方法:

async def start() -> None:
    """启动引擎，加载模型"""

async def stop() -> None:
    """停止引擎，释放资源"""

async def generate(
    prompt: str | list[int],
    *,
    sampling_params: SamplingParams | None = None,
    max_tokens: int | None = None,
    request_id: str | None = None,
) -> Response:
    """同步推理，返回完整输出"""

async def stream(
    prompt_or_request: str | Request,
    *,
    max_tokens: int | None = None,
    request_id: str | None = None,
) -> AsyncIterator[StreamEvent]:
    """流式推理，逐 token 返回事件"""

async def execute(request: Request) -> Response:
    """执行 Protocol Request，用于兼容旧接口"""

SamplingParams - 采样参数

from sagellm_protocol.sampling import SamplingParams, DecodingStrategy

SamplingParams(
    strategy: DecodingStrategy = DecodingStrategy.GREEDY,
    temperature: float = 0.0,   # 越高越随机
    top_p: float = 1.0,         # Nucleus 采样
    top_k: int = 0,             # Top-K 采样
    repetition_penalty: float = 1.0,
    length_penalty: float = 1.0,
    num_beams: int = 1,         # Beam Search 宽度
    max_tokens: int = 128,
    seed: int | None = None,    # 可复现性
)

其他核心 API

# 配置加载（Legacy）
from sagellm_core import load_config
config = load_config("config.yaml")  # 支持 YAML/JSON

# 后端创建（Legacy）
from sagellm_core import create_backend, BackendConfig
backend = create_backend(BackendConfig(kind="cpu"))

# 工厂方法（Legacy）
from sagellm_core import EngineFactory
factory = EngineFactory()
engine = factory.create("cpu")  # 支持自动发现

🏗️ 架构设计

分层架构

┌──────────────────────────────────┐
│    LLMEngine (对外 API)           │  ← 用户交互层
│  • generate/stream/execute       │
└────────┬─────────────────────────┘
         │
┌────────▼──────────────────────────┐
│    EngineCore (引擎核心)          │  ← 推理协调层
│  • Scheduler: Continuous Batching │
│  • Executor: 工作进程管理          │
│  • KVCacheManager: 缓存管理        │
└────────┬──────────────────────────┘
         │
┌────────▼──────────────────────────┐
│    Worker & ModelRunner           │  ← 执行层
│  • 前向传播                        │
│  • TP/PP 通信                      │
│  • 硬件资源管理                    │
└────────┬──────────────────────────┘
         │
    ┌────┴────┬───────────┬────────────┐
    ▼         ▼           ▼            ▼
  Backend   Comm      KV-Cache     Protocol

模块说明

模块	路径	职责
llm_engine	src/sagellm_core/llm_engine.py	统一推理入口
engine_core	src/sagellm_core/engine_core/	调度与执行协调
scheduler	src/sagellm_core/engine_core/scheduler.py	Continuous Batching
executor	src/sagellm_core/executor/	Worker 管理
worker	src/sagellm_core/worker/	单设备执行
decoding	src/sagellm_core/decoding/	5+ 种解码策略
runtime	src/sagellm_core/runtime.py	PD 分离 Runtime
pd_executor	src/sagellm_core/pd_executor.py	Prefill/Decode 分离
engine_server	src/sagellm_core/engine_server.py	HTTP 服务

🔧 开发指南

项目结构

sagellm-core/
├── src/sagellm_core/           # 源代码
│   ├── llm_engine.py           # 统一推理引擎
│   ├── engine_core/            # 引擎核心（调度+执行）
│   ├── executor/               # Worker 执行器
│   ├── worker/                 # Worker 和 ModelRunner
│   ├── decoding/               # 解码策略（Greedy/Sampling/...)
│   ├── engine_server.py        # HTTP Server (FastAPI)
│   ├── config.py               # 配置类（Legacy）
│   ├── factory.py              # 工厂方法（Legacy）
│   ├── runtime.py              # PD 分离 Runtime
│   ├── pd_executor.py          # PD 分离执行器
│   └── ...
├── tests/                      # 测试用例
│   ├── unit/                   # 单元测试
│   ├── integration/            # 集成测试
│   ├── e2e/                    # 端到端测试
│   └── conftest.py             # Pytest 配置
├── examples/                   # 示例代码
│   ├── config_cpu.yaml         # CPU 配置示例
│   ├── config_cuda.yaml        # CUDA 配置示例
│   ├── decoding_strategies_demo.py  # 解码策略演示
│   ├── pd_separation_demo.py   # PD 分离演示
│   └── ...
├── docs/                       # 文档
│   ├── ARCHITECTURE.md         # 详细架构
│   ├── DECODING_STRATEGIES.md  # 解码策略指南
│   └── ...
├── pyproject.toml              # 项目配置（setuptools）
├── pytest.ini                  # Pytest 配置
├── .pre-commit-config.yaml     # Pre-commit hooks
└── quickstart.sh               # 快速安装脚本

环境设置

# 克隆并进入项目
git clone https://github.com/intellistream/sagellm-core.git
cd sagellm-core

# 安装开发依赖
pip install -e ".[dev]"

# 安装 git hooks（提交前自动检查）
pre-commit install

# 验证安装
python -m pytest tests/test_ci_smoke.py -v

运行测试

# 运行所有测试
pytest tests/ -v

# 运行特定测试模块
pytest tests/unit/test_config.py -v

# 运行带覆盖率报告
pytest tests/ --cov=sagellm_core --cov-report=html

# 运行 slow 标记的测试（包括 LLM 测试）
pytest tests/ -v -m slow

# 运行单个测试用例
pytest tests/test_llm_engine.py::test_engine_generate -v

代码质量检查

# Ruff 代码格式化 + Lint 检查
ruff check . --fix       # 自动修复可修复的问题
ruff format .            # 格式化代码

# Mypy 静态类型检查
mypy src/

# 手动运行所有 pre-commit hooks
pre-commit run --all-files

# 运行特定 hook
pre-commit run ruff --all-files
pre-commit run mypy --all-files

Git 提交流程

1. 创建特性分支

   git checkout -b feature/your-feature-name
   

2. 提交代码（hooks 会自动检查）

   git add .
   git commit -m "feat: add your feature description"
   

   • 如果 hooks 失败，修复问题后重新提交

3. 推送并提 PR

   git push origin feature/your-feature-name
   

常见开发任务

添加新的解码策略:

1. 在 src/sagellm_core/decoding/ 创建新文件
2. 继承 BaseDecodingStrategy
3. 实现 __call__() 方法
4. 在 __init__.py 中导出
5. 添加单元测试

添加新的后端支持:

1. 在 sagellm-backend 实现 BackendProvider
2. 在 Core 中使用 get_provider() 自动发现
3. 添加集成测试

添加配置选项:

1. 修改 src/sagellm_core/config.py 中的 Pydantic 模型
2. 在示例配置文件中更新示例
3. 更新文档和测试

📖 示例代码

完整的演示应用

# 运行解码策略完整演示（包含 6 个场景）
python examples/decoding_strategies_demo.py

# 运行 PD 分离演示
python examples/pd_separation_demo.py

CPU-First 测试

所有测试默认在 CPU 上运行（无 GPU 要求）：

# 测试 LLMEngine
pytest tests/test_engine.py -v

# 测试配置系统
pytest tests/test_config.py -v

# 测试解码策略
pytest tests/test_decoding_strategies.py -v

# 测试 E2E 流程
pytest tests/test_llm_engine_contract.py -v

模型下载

使用提供的帮助脚本下载测试模型：

# 下载 tiny-gpt2（用于测试）
python examples/model_download_helper.py

# 或手动下载
python -c "from transformers import AutoModel; AutoModel.from_pretrained('sshleifer/tiny-gpt2')"

🔄 持续集成

本项目使用 GitHub Actions 进行 CI/CD：

• 单元测试: 每次 push 运行 pytest tests/unit/
• 集成测试: 每次 push 运行 pytest tests/integration/
• Lint 检查: Ruff、Mypy、YAML 验证
• 覆盖率: 维持 >80% 的代码覆盖率

查看 CI 配置：.github/workflows/ci.yml

📋 版本与变更

当前版本: 0.4.0.17 (Alpha)

支持的 Python: 3.10, 3.11, 3.12

完整变更日志: 见 CHANGELOG.md

最近更新 (v0.4.0.17):

• ✅ 采样参数标准化（issue #22）- 参数优先级系统
• ✅ 增强解码策略测试
• ✅ 完成 LLMEngine 与解码策略的集成测试
• ✅ 解码策略使用演示与文档

🤝 贡献指南

我们欢迎社区贡献！请遵循以下步骤：

1. Fork 仓库
2. 创建特性分支 (git checkout -b feature/your-feature)
3. 提交更改 (git commit -m "feat: description")
4. 推送到分支 (git push origin feature/your-feature)
5. 提交 Pull Request

提交规范

使用 Conventional Commits：

feat: 新增功能
fix: 修复 bug
docs: 文档更新
test: 测试相关
refactor: 代码重构
perf: 性能优化

📄 许可证

Proprietary - IntelliStream

📞 反馈与支持

• 📍 GitHub Issues: 提交问题
• 💬 讨论: 启动讨论
• 📧 Email: [e-mail]

相关资源

• 🔗 Protocol v0.1 文档
• 🔗 sagellm-backend
• 🔗 sagellm-comm
• 🔗 sagellm-kv-cache
• 🔗 完整架构文档
• 🔗 解码策略指南

Continuous Integration

GitHub Actions automatically runs on each PR:

• Code linting and formatting checks
• Tests across Python 3.10, 3.11, 3.12
• Package build verification

Code Style

This project uses:

• Ruff for formatting and linting
• Mypy for type checking
• Type hints are required for all functions

For detailed guidelines, see CONTRIBUTING.md

代码检查

# 格式化代码
ruff format .

# Lint 检查
ruff check .

# 类型检查
mypy src/sagellm_core

# 一键检查所有
pre-commit run --all-files

依赖

• pydantic>=2.0.0: 配置校验
• pyyaml>=6.0.0: YAML 配置支持
• isagellm-protocol>=0.4.0.0,<0.5.0: 协议定义
• isagellm-backend>=0.4.0.0,<0.5.0: 后端抽象
• isagellm-comm>=0.4.0.0,<0.5.0: 通信后端
• isagellm-kv-cache>=0.4.0.0,<0.5.0: KV 缓存

Related Packages

• isagellm-protocol - Protocol definitions (L0)
• isagellm-backend - Backend abstraction layer (L1)
• isagellm-comm - Communication abstraction (L1)
• isagellm-kv-cache - KV Cache management (L1.5)
• sagellm-control-plane - Cross-engine orchestration (L3)
• sagellm-gateway - OpenAI-compatible API (L4)

For the complete ecosystem, see sageLLM organization

---

Last Updated: 2026-02-02 | Status: Alpha (v0.4.0.17) | Protocol: v0.1