SAG

环境要求

• Docker Desktop，或带 Compose v2 的 Docker Engine
• 启动阶段无需 API Key、Python/Node 运行时或外部数据库
• 索引与向量检索需要 OpenAI 兼容的 Embedding 端点
• 事件抽取、查询理解与生成答案需要 OpenAI 兼容的 LLM 端点
• （可选）生产级部署需要 PostgreSQL/pgvector 支持

安装与启动步骤

1. 1克隆项目仓库

   把 SAG 源码拉到本地并进入项目目录，后续所有命令都在该目录执行。

   git clone https://github.com/Zleap-AI/SAG.git
   cd SAG

   复制

2. 2Docker 一键启动

   使用 Compose 构建并后台启动全部服务，首次构建耗时较长请耐心等待。

   docker compose up -d --build

   复制

3. 3打开 Web 与 API 文档

   两个服务健康后，浏览器访问 Web 应用与 API 文档确认界面可用。

4. 4创建本地身份

   首次启动时输入你的名字，用于创建或恢复本地身份。

5. 5配置模型端点

   使用 302.AI 快速配置，或进入 Settings → Models 配置任意 OpenAI 兼容的 LLM 与 Embedding 端点。

6. 6上传文档并检索

   创建 source 并上传文档，等待状态变为 Ready 后即可搜索、打开原文或发起带引用的对话。

7. 7安装 Agent Skill（可选）

   Skill 随 @zleap-ai/sag-cli 提供，将其复制到你的 Agent skills 目录即可使用。

8. 8PostgreSQL 生产部署（可选）

   切换到 PostgreSQL/pgvector 覆盖配置，先写入随机密钥与密码再启动，升级前务必备份数据卷。

   cp .env.example .env
   openssl rand -hex 32
   openssl rand -hex 24
   docker compose -f compose.yaml -f compose.postgres.yaml config
   docker compose -f compose.yaml -f compose.postgres.yaml up -d --build

   复制

关键配置

如何确认成功

浏览器能打开 http://localhost:3000 的 Web 应用、http://localhost:8000/docs 的 API 文档，即两个服务均健康启动。

常见问题

注意事项

• 启动应用不需要 API Key、Python 运行时、Node 运行时或外部数据库。
• EngineConfig(...) 不会隐式读取环境变量，必须显式传参或使用 from_env()。
• 如需单独的嵌入端点，可用 EmbeddingConfig(api_key=..., base_url=..., model=...) 指定。
• 服务器部署前需设置真实的 SAG_CORS_ORIGINS 与 NEXT_PUBLIC_API_BASE；升级前备份 pgdata 和 sagdata。