sage
与任意代码库对话的开源 RAG 工具，支持本地 Ollama+Marqo 或云端 OpenAI+An
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
与任意代码库对话的开源 RAG 工具，支持本地 Ollama+Marqo 或云端 OpenAI+An
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
当你接手一个陌生的代码库时，最痛苦的经历是什么？是面对数千行代码不知从哪下手，还是在集成第三方库时翻遍文档仍找不到关键答案？传统的代码阅读方式——逐文件阅读、用 IDE 全局搜索、泡在 Discord/Slack 里等回复——效率极低，尤其是当代码库体量达到数万行时。
Sage 正是为了解决这个痛点而诞生。它由 AI 创业公司 Storia-AI 开发，定位为「开源版 GitHub Copilot」，让你在不到两分钟内与任意代码库对话，理解其工作原理、集成方式。
Storia-AI 是一家专注于代码智能的初创公司，创始团队来自学术界，对代码索引和信息检索有深入研究。Sage 项目于 2024 年初开源，迅速在 GitHub 获得 1200+ stars，Discord 社区活跃，被收录于 LangChain 官方生态和 Anthropic 官方 Cookbook。
项目的核心理念是：让代码可搜索、可理解。团队还在运营托管服务 sage.storia.ai，已预索引了一批主流开源库，用户只需粘贴 GitHub URL 即可开始对话。
Sage 的工作流分为索引（Index）和对话（Chat）两个阶段，通过两个 CLI 命令驱动：
sage-indexsage-index Storia-AI/sage --llm-retriever
这一步完成三件事：
GitPython 拉取代码，支持指定 commit hash.ipynb）和普通代码文件分块策略非常精细：文件路径作为前缀，拼接到每个 chunk 开头，让 LLM 知道这段代码属于哪个文件。分块大小由 tokens-per-chunk 控制（默认 800 tokens）。
sage-chatsage-chat --repo-id Storia-AI/sage --share
启动一个 Gradio Web UI（可公开分享），构建完整的 RAG 链路：
create_history_aware_retriever 让对话记住上下文，自动将口语化问题改写为独立查询图1：Storia-AI/sage GitHub 仓库概览（来源：GitHub）
Sage 的设计亮点之一是提供了两套检索策略，在易用性和效果之间做了权衡：
| 模式 | 检索策略 | 索引需求 | 依赖 | 适用场景 |
|---|---|---|---|---|
| Remote（默认） | LLM Retriever（Claude） | 无需索引 | Anthropic API Key | 快速上手、轻量级 |
| Local | 向量检索 + BM25 | 先运行 sage-index | Ollama + Marqo | 追求精准检索、离线隐私 |
Remote 模式跳过了索引步骤，依赖 Claude 的上下文窗口和 Prompt Caching 能力，直接将仓库文件结构发送给 LLM，由 LLM 决策最相关的文件。这对于小型代码库非常友好，但对大代码库可能较慢。
图2：Sage 系统架构——从代码索引到智能问答的全流程（来源：GitHub）
1. sage/data_manager.py — 数据层抽象
通过 DataManager 基类 + GitHubRepoManager 实现，数据源可扩展。walk() 方法统一了文件遍历接口，过滤规则通过 inclusion/exclusion 文件配置，支持 ext:.py、file:xxx、dir:xxx 三种格式。
2. sage/chunker.py — 语义分块
这是技术含量最高的模块之一。使用 Tree-sitter 解析代码 AST，在语法树节点边界切分，而非简单按字符数切分。好处是每个 chunk 都是完整的语法单元（函数、类、import 块），语义完整性高。
支持的文件类型：
tree-sitter-language-pack）.ipynb），通过 nbformat 解析3. sage/embedder.py — 批量化向量化
支持多种 Embedding 提供商：
text-embedding-3-small / text-embedding-3-large / ada-002，使用官方 Batch API 降低费用voyage-2-code 等代码专用模型google-ai-generativelanguage 接入e5-base-v2批处理逻辑：文件逐个读取→分块→积累到 chunks_per_batch 阈值→批量提交 API job→异步轮询状态→下载结果。
4. sage/vector_store.py — 向量存储
抽象了六种向量存储后端，统一 upsert、as_retriever 接口。通过 LangChain 的 EnsembleRetriever 实现 BM25 + 向量检索混合模式。
5. sage/retriever.py — 检索层
核心类 LLMRetriever 是亮点：不依赖向量数据库，直接将仓库目录树序列化后发给 Claude，让 LLM 自主判断最相关的文件路径。这在 remote.yaml 配置文件中有体现（llm-retriever: true）。
普通向量检索则通过 LangChain 的 MultiQueryRetriever 生成多个查询变体，扩大召回面。
6. sage/reranker.py — 重排序
支持六种重排序方案，默认使用 HuggingFace 的 cross-encoder/ms-marco-MiniLM-L-6-v2。重排序位于检索之后，用于精排，是提升最终答案质量的关键步骤。
7. sage/llm.py — LLM 统一接入
通过 LangChain 封装 OpenAI / Anthropic / Ollama 三种 LLM Provider，对话系统统一使用 build_llm_via_langchain() 工厂函数。
# 历史感知的检索链
contextualize_q_chain → history_aware_retriever → qa_chain
contextualize_q_chain：将多轮对话中的历史问题「折叠」成独立查询history_aware_retriever：基于折叠后的问题，从向量库/文件系统中检索相关上下文qa_chain：将上下文注入 prompt，生成最终回答prompt 设计简洁有力："You are my coding buddy... assume I am an advanced developer and answer in the most succinct way possible."
项目内置了 benchmarks/retrieval/ 目录，详细记录了不同 Embedding 模型、检索策略、重排序方案在自有测试集上的表现。这在同类开源项目中非常罕见，体现了团队对工程严谨性的追求。
1. Python 版本限制严格：仅支持 Python 3.9-3.11，不支持 3.12+，这对使用新版本 Python 的开发者造成障碍。
2. raw.githubusercontent.com 在国内访问受限：大量 AI 开发者在国内环境使用时，pip install 依赖解析和模型下载都可能遇到网络问题，需要配置代理。
3. LLM Retriever 仅支持 Claude：Remote 模式的最优体验绑定 Anthropic，对 OpenAI 或本地模型用户不友好。
4. 缺少生产级部署方案：无 Dockerfile、无 docker-compose，缺乏 Helm Chart，团队推荐的是手动 pip install + YAML 配置，对于不熟悉 Python 环境的用户门槛较高。
Sage 代表了 Code RAG（代码检索增强生成） 这一细分方向的最新实践。与传统代码搜索引擎（Sourcegraph）相比，Sage 的优势在于无需额外基础设施，开发者本地即可运行；与 GitHub Copilot 的闭源黑盒相比，Sage 完全开源透明，用户可以替换任意 Embedding/LLM/VectorStore 组件。
从技术趋势看，代码智能问答正在从「通用 LLM + 提示词工程」向「专用代码嵌入 + 多阶段检索」演进。Sage 的模块化设计恰好契合这一方向——既可以作为开箱即用的产品，也可以作为构建自定义代码问答系统的框架。