# sagellm-core

![CI](https://github.com/intellistream/sagellm-core/actions/workflows/ci.yml/badge.svg)
[![PyPI](https://img.shields.io/pypi/v/isagellm-core.svg)](https://pypi.org/project/isagellm-core/)
[![Python](https://img.shields.io/pypi/pyversions/isagellm-core.svg)](https://pypi.org/project/isagellm-core/)
[![License](https://img.shields.io/github/license/intellistream/sagellm-core.svg)](https://github.com/intellistream/sagellm-core/blob/main/LICENSE)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

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

**版本**: `0.4.0.17` | **最后更新**: 2026-02-02 | **协议遵循**: [Protocol v0.1](https://github.com/intellistream/sagellm-docs/blob/main/docs/specs/protocol_v0.1.md)

## 📍 职责定位

在整个 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 方案

## ✨ 核心特性

| 特性 | 说明 |
|------|------|
| **统一推理接口** | `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 支持 |

## 📦 依赖关系

### 核心依赖（自动安装）

```toml
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 安装（推荐）

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

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

### 本地开发安装

```bash
# 克隆仓库
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` 跳过）
- 失败时会输出详细诊断日志，便于定位安装问题

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

```bash
# 如果同时在开发 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]"
```

### 验证安装

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

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

## 🎯 快速开始

### 1. 基础推理

```python
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. 使用采样参数控制生成

```python
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

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

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

# 查看输出 metrics
cat metrics.json
```

### 4. 启动 HTTP Server

```bash
# 方式 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 请求示例

```bash
# 同步推理
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 - 主入口

**初始化**:
```python
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
)
```

**关键方法**:
```python
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 - 采样参数

```python
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

```python
# 配置加载（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               # 快速安装脚本
```

### 环境设置

```bash
# 克隆并进入项目
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
```

### 运行测试

```bash
# 运行所有测试
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
```

### 代码质量检查

```bash
# 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. **创建特性分支**
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **提交代码（hooks 会自动检查）**
   ```bash
   git add .
   git commit -m "feat: add your feature description"
   ```
   - 如果 hooks 失败，修复问题后重新提交

3. **推送并提 PR**
   ```bash
   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. 更新文档和测试

## 📖 示例代码

### 完整的演示应用

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

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

### CPU-First 测试

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

```bash
# 测试 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
```

### 模型下载

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

```bash
# 下载 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](.github/workflows/ci.yml)

## 📋 版本与变更

**当前版本**: `0.4.0.17` (Alpha)

**支持的 Python**: 3.10, 3.11, 3.12

**完整变更日志**: 见 [CHANGELOG.md](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**: [提交问题](https://github.com/intellistream/sagellm-core/issues)
- 💬 **讨论**: [启动讨论](https://github.com/intellistream/sagellm-core/discussions)
- 📧 **Email**: team@intellistream.ai

## 相关资源

- 🔗 [Protocol v0.1 文档](https://github.com/intellistream/sagellm-docs/blob/main/docs/specs/protocol_v0.1.md)
- 🔗 [sagellm-backend](https://github.com/intellistream/sagellm-backend)
- 🔗 [sagellm-comm](https://github.com/intellistream/sagellm-comm)
- 🔗 [sagellm-kv-cache](https://github.com/intellistream/sagellm-kv-cache)
- 🔗 [完整架构文档](docs/ARCHITECTURE.md)
- 🔗 [解码策略指南](docs/DECODING_STRATEGIES.md)


#### 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](CONTRIBUTING.md)

### 代码检查

```bash
# 格式化代码
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](https://github.com/intellistream/sagellm)

---

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