zleap-sag Python 引擎

zleap-sag 是 SAG 应用底层持续维护的 Python 知识引擎。发行名为 zleap-sag，导入路径为 zleap.sag，要求 Python 3.11+，使用 MIT 许可。

安装

默认本地组合使用 SQLite 与 LanceDB，不需要外部数据库：

pip install zleap-sag

SAG 应用当前要求 zleap-sag>=0.7.1。

完整生命周期

import asyncio

from zleap.sag import DataEngine, EngineConfig
from zleap.sag.config import EmbeddingConfig, LLMConfig


async def main() -> None:
    config = EngineConfig(
        llm=LLMConfig(
            api_key="sk-...",
            base_url="https://your-openai-compatible-host/v1",
            model="qwen3.6-flash",
        ),
        embedding=EmbeddingConfig(model="bge-large-en-v1.5"),
        language="zh",
    )

    async with DataEngine(config) as engine:
        ingest = await engine.ingest("knowledge.md")
        extract = await engine.extract()
        result = await engine.search(
            "SAG 为什么适合多跳检索？",
            strategy="multi",
            top_k=5,
        )

        print(ingest.chunk_count, extract.event_count)
        for section in result.sections:
            print(section.get("content", "")[:200])


asyncio.run(main())

一个 DataEngine 实例代表一个逻辑信源。本地数据会自动创建在 ./.zleap/，应把该目录加入 .gitignore。

配置方式

两种方式选择其一：

方式	创建方法	适合场景
参数注入	`EngineConfig(llm=..., embedding=...)`	库、Notebook、显式应用装配
环境变量	`EngineConfig.from_env()`	容器与 12-factor 服务

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://your-openai-compatible-host/v1
LLM_MODEL=qwen3.6-flash
EMBEDDING_MODEL=bge-large-en-v1.5

from zleap.sag import EngineConfig

config = EngineConfig.from_env()

EngineConfig(...) 不会隐式读取环境变量。Embedding 若使用独立端点，应显式创建 EmbeddingConfig(api_key=..., base_url=..., model=...)。

DataEngine API

方法	作用
`await engine.start()`	初始化连接与本地 Schema
`await engine.aclose()`	关闭资源；`async with` 会自动执行
`await engine.chunk(source)`	解析并分块路径或原始字符串，不持久化
`await engine.ingest(path, ...)`	分块、向量化并持久化 chunks/vectors
`await engine.extract(...)`	抽取并保存 event-entity 索引
`await engine.search(...)`	返回 `SearchResult`、sections 与统计信息
`await engine.init_schema()`	幂等初始化生产 Schema

类型化结果位于 zleap.sag.results：ChunkResult、IngestResult、ExtractResult 和 SearchResult。所有引擎异常继承 SagError。

存储后端

部署	关系型存储	向量存储	extra
本地默认	SQLite	LanceDB	无
单数据库	PostgreSQL	pgvector	`zleap-sag[postgres]`
生产拆分	MySQL/PostgreSQL/OceanBase	Elasticsearch	`[mysql]`、`[postgres]`、`[es]`
OceanBase	OceanBase 4.3.3+	OceanBase vector	`[mysql]`

改变 EngineConfig 不需要改写 ingest、extract 和 search 调用。当前连接是进程级全局资源，一个进程应只使用一份 EngineConfig。