SAGE Middleware（中间件）

用于构建带有 AI 能力的流式数据应用的中间件层

📋 Overview

SAGE Middleware 是 SAGE 框架的 L4 中间件层，提供高性能的数据处理组件和 AI 能力集成。它集成了多家大模型提供商、异步任务调度、安全鉴权以及核心数据处理组件（向量数据库、流处理引擎等）。

🧭 Governance / 团队协作制度

本仓库协作规范与质量门槛请参考：

• .github/copilot-instructions.md
• quickstart.sh
• hooks/pre-commit
• hooks/pre-push

✨ Key Features

• 🤖 LLM 推理：
  • sageLLM ✅ 推荐：统一 LLM 推理引擎，支持 CUDA/Ascend/Mock 后端
• 🔎 检索与向量：RAG、BM25、FAISS 等
• 📋 任务调度：Celery 异步任务
• 🔐 安全鉴权：JWT、密码学工具
• ⚙️ 核心组件：
  • sage_db：数据库/向量存储相关组件（含 C/C++ 扩展）
  • sage_flow：高性能向量流处理（独立包 isage-flow，SAGE 仅保留兼容层）

🚀 Installation

Basic Installation

pip install isage-middleware

Development Installation

git clone https://github.com/intellistream/SAGE.git
cd SAGE/packages/sage-middleware
pip install -e .

说明：中间件组件能力通过源码或独立 PyPI 包分发；sage_tsdb 请直接安装 isage-tsdb，无需初始化任何子模块。

With Optional Dependencies

# 安装全部能力包（ML + Vector + Memory + Stream）
pip install isage-middleware[capability-all]

# 仅安装 ML 能力包
pip install isage-middleware[capability-ml]

# 仅安装向量能力包
pip install isage-middleware[capability-vector]

# 仅安装内存能力包
pip install isage-middleware[capability-memory]

# 仅安装流式能力包
pip install isage-middleware[capability-stream]

📖 Quick Start

LLM 推理（推荐：sageLLM）

from sage.middleware.operators.llm import SageLLMGenerator

# 自动选择最佳后端
generator = SageLLMGenerator(
    model_path="Qwen/Qwen2.5-7B-Instruct",
  base_url="http://127.0.0.1:8901/v1",  # 单一推理端口（可省略使用默认）
    temperature=0.7,
    max_tokens=2048,
)

result = generator.execute("你好，世界！")
print(result)

API 客户端

from sage.middleware.api.client import APIClient
from sage.middleware.auth.jwt import JWTManager

client = APIClient()
jwt_manager = JWTManager()

resp = client.chat_completion(
    provider="openai",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp)

📖 说明：LLM 推理默认使用 sageLLM，建议通过统一配置管理模型后端。

📦 Package Structure

sage-middleware/
├── src/
│   └── sage/
│       └── middleware/
│           ├── __init__.py
│           ├── operators/          # Dataflow operators
│           │   ├── llm/           # LLM operators (sageLLM)
│           │   ├── rag/           # RAG operators
│           │   └── agentic/       # Agent operators
│           ├── components/         # Core components
│           │   ├── sage_db/       # Vector database (C++ extensions)
│           │   ├── sage_flow/     # Stream processing (C++ extensions)
│           │   ├── sage_mem/      # Memory management
│           │   └── sage_refiner/  # Context compression
│           ├── api/                # API clients
│           └── auth/               # Authentication
├── tests/
│   ├── unit/
│   └── integration/
├── docs/
│   └── governance/                # Team collaboration
├── README.md
├── pyproject.toml
└── setup.py

🔧 Configuration

配置可以通过以下方式提供：

• 环境变量
• YAML/TOML 配置文件
• 直接通过 API 参数

配置示例

# config.yaml
middleware:
  auth:
    secret_key: "your-secret-key"  # pragma: allowlist secret
    algorithm: "HS256"
  providers:
    openai:
      api_key: "sk-..."  # pragma: allowlist secret
      base_url: "https://api.openai.com/v1"

📚 Documentation

• 用户指南: 参见 SAGE-Pub
• API 参考: 参见 API 文档
• 治理文档: 参见 docs/governance/
• 迁移指南: 参见 Project Changelog

🧪 Testing

# 重依赖声明与调用点一致性审计（Issue #8）
python tools/dependency_audit.py --check

# 运行单元测试
pytest tests/unit -v

# 运行集成测试
pytest tests/integration -v

# 运行所有测试并生成覆盖率报告
pytest --cov=sage.middleware --cov-report=html

🤝 Contributing

欢迎贡献！请参阅：

• 贡献指南: CONTRIBUTING.md
• 开发者文档: DEVELOPER.md
• PR 检查清单: docs/governance/PR_CHECKLIST.md

新增中间件组件规范

当添加新的中间件组件时，请遵循以下要求：

1. 目录结构: 在 src/sage/middleware/components/ 下创建组件目录
2. C++ 扩展: 如包含 C++ 扩展，必须遵守依赖约束（参见下文详细规范）
3. 构建脚本: 提供标准的 build.sh，支持 --install-deps
4. setup.py 集成: 在 setup.py 中添加构建方法
5. 测试: 添加单元测试和集成测试
6. 文档: 更新 README 和相关文档

📄 License

本项目采用 MIT License - 详见 LICENSE 文件

🔗 Related Packages

• sage-kernel: 核心计算引擎（L3）
• sage-common: 通用工具（L1）
• sage-libs: 可复用算法库（L3）
• sage-platform: 平台服务（L2）
• isage-vdb: 向量数据库（独立包）
• isage-neuromem: 内存管理系统（独立包）
• isage-refiner: 上下文压缩（独立包）

📮 Support

• 文档: https://intellistream.github.io/SAGE-Pub/
• 问题反馈: https://github.com/intellistream/SAGE/issues
• 讨论: https://github.com/intellistream/SAGE/discussions

Part of the SAGE Framework | 主仓库