SAGE Common

SAGE 框架的核心工具和共享组件

📋 Overview

SAGE Common 提供所有 SAGE 包共用的基础工具和组件。 这是基础层（L1），提供：

• 配置管理 - YAML/TOML 文件支持
• 日志框架 - 自定义格式化器和处理程序
• 网络工具 - TCP/UDP 通信支持
• 序列化工具 - dill 和 pickle 支持
• 系统工具 - 环境和进程管理
• 嵌入服务适配 - sage_embedding client/protocol 适配（service-backed only）

该包确保 SAGE 生态系统的一致性并减少代码重复。

🧭 Governance / 团队协作制度

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

• 统一配置 - YAML/TOML 配置加载和验证

• 高级日志 - 彩色输出、结构化日志、自定义格式器

• 网络工具 - TCP 客户端/服务器、网络助手 sage-common 作为 L1 基础层，embedding 仅承担 client/protocol 适配职责：

• ✅ 保留：协议、工厂、wrapper、服务端点客户端转发（service-backed）

• ❌ 不承载：本地模型生命周期（下载、加载、设备管理、推理执行）

🚀 Quick Start

配置管理

from sage.common.utils.config import load_config

# 加载 YAML 配置
config = load_config("config.yaml")
print(config["database"]["host"])

日志记录

from sage.common.utils.logging import get_logger

logger = get_logger(__name__)
logger.info("Processing started")
logger.error("An error occurred", extra={"user_id": 123})

序列化

from sage.common.utils.serialization import UniversalSerializer

serializer = UniversalSerializer()
data = {"key": "value", "nested": {"data": [1, 2, 3]}}
serialized = serializer.serialize(data)
deserialized = serializer.deserialize(serialized)

核心模块

• utils.config - 配置管理工具
• utils.logging - 日志框架和格式化器
• utils.network - 网络工具和 TCP 客户端/服务器
• utils.serialization - 序列化工具（包含 dill 支持）
• utils.system - 环境和进程管理的系统工具
• _version - 版本管理

📦 Package Structure

sage-common/
├── src/
│   └── sage/
│       └── common/
│           ├── __init__.py
│           ├── _version.py
│           ├── utils/                  # 核心工具
│           │   ├── config/            # 配置管理
│           │   ├── logging/           # 日志框架
│           │   ├── network/           # 网络工具
│           │   ├── serialization/     # 序列化工具
│           │   └── system/            # 系统工具
│           └── components/            # 共享组件
│               ├── sage_embedding/    # 嵌入服务
│               └── sage_llm/         # sageLLM 服务
├── tests/
├── pyproject.toml
└── README.md

🚀 Installation

基础安装

pip install isage-common

开发安装

cd packages/sage-common
pip install -e .

可选依赖安装

# 开发工具（pytest / ruff / 覆盖率等）
pip install isage-common[dev]

📖 快速开始

配置管理

from sage.common.utils.config.loader import ConfigLoader

# 加载配置
config = ConfigLoader("config.yaml")

# 访问配置
model_name = config.get("model.name", default="default-model")

日志

from sage.common.utils.logging.custom_logger import get_logger

# 获取日志器
logger = get_logger(__name__)

# 使用日志器
logger.info("应用程序已启动")
logger.debug("调试信息")
logger.error("发生错误", exc_info=True)

网络工具

from sage.common.utils.network import TCPClient, TCPServer

# 创建 TCP 服务器
server = TCPServer(host="localhost", port=8080)
server.start()

# 创建 TCP 客户端
client = TCPClient(host="localhost", port=8080)
client.connect()
client.send(b"你好，服务器！")

序列化

from sage.common.utils.serialization import serialize, deserialize

# 序列化数据
data = {"key": "value", "numbers": [1, 2, 3]}
serialized = serialize(data, format="dill")

# 反序列化数据
restored = deserialize(serialized, format="dill")

🔧 Configuration

配置文件通常使用 YAML 或 TOML 格式：

# config.yaml
logging:
  level: INFO
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

network:
  host: localhost
  port: 8080
  timeout: 30

embedding:
  model: BAAI/bge-m3
  method: sagellm
  base_url: http://localhost:8000

🧪 Testing

# 运行单元测试
pytest tests/unit

# 运行集成测试
pytest tests/integration

# 运行覆盖率测试
pytest --cov=sage.common --cov-report=html

📚 Documentation

• 用户指南 - 查看 sage-docs
• API 参考 - 查看包文档字符串和类型提示
• 示例 - 查看各模块中的 examples/ 目录

🤝 Contributing

欢迎贡献！请查看 CONTRIBUTING.md 了解指导原则。

📄 License

该项目采用 MIT 许可证 - 详情请查看 LICENSE 文件。

🔗 相关包

• sage-kernel - 使用通用工具进行运行时管理
• sage-libs - 基于通用组件构建库
• sage-middleware - 使用网络和序列化工具
• sage-tools - 使用配置和日志工具

📮 支持

• 文档 - https://intellistream.github.io/sage-docs/
• 问题 - https://github.com/intellistream/SAGE/issues
• 讨论 - https://github.com/intellistream/SAGE/discussions

SAGE 框架的一部分 | 主仓库