Open Documents

OpenDocuments

Open source RAG tool for AI document search — connect GitHub, Notion, Google Drive and ask questions with cited answers

______________________________________________________________________

问题：知识分散，没有人工智能搜索

你的团队的知识被困在孤岛中：

• 工程文档 live in GitHub自述文件和维基页面
• 产品规格 分散在Notion数据库中
• 预算报告 坐在谷歌驱动器上的Excel文件中
• API文件 是自动生成的Swagger规格，没有人阅读
• 会议记录 汇流空间腐烂
• 入职指南 埋在 .docx S3上的文件

当有人问 _“我们的身份验证系统是如何工作的？”_ 或 _“人工智能团队的第三季度预算是多少？”_，他们花了15分钟搜寻5种不同的工具。他们可能仍然找不到答案。

解决方案：自托管AI文档搜索

打开文档 连接到所有文档源, 将所有内容编入统一的搜索引擎，以及 用自然语言回答问题 --有来源引用，这样你就可以确切地知道答案来自哪里。

npm install -g opendocuments
opendocuments init
opendocuments start

打开 http://localhost:3000，然后走开。

打开文档 是专有企业人工智能搜索工具的免费开源替代品。这是一个在您自己的基础设施上运行的自托管RAG（检索增强代）平台。

最近的改进

• RAG精度检修：结构保持分块、上下文前缀、HyDE+多查询检索、父文档召回、命题增强、重新排序和自适应上下文拟合
• 工作区范围的团队模式：管理/聊天/文档API位于经过身份验证的工作区内，具有共享的会话链接以及会话和API-key身份验证支持
• 备份和恢复CLI：使用一个命令快照SQLite+LanceDB数据并恢复实例
• 插件硬化：插件搜索/安装路由仅限管理员，并使用经过验证的npm参数执行
• 一键式Ollama设置: init 汽车检测到Ollama，主动提出召回丢失的车型
• .env 自动加载：中的API密钥 .env 自动加载（无需手动导出）
• 多回合对话：聊天会记住之前的上下文，以便后续提问
• 降级模式警告：未配置模型时清除横幅，并附上修复说明
• 增强的诊断: opendocuments doctor 检查Ollama连接、模型可用性和配置有效性
• 安全强化：FTS5注射预防、文件上传净化、OAuth状态限制、工作区隔离

______________________________________________________________________

真实世界用例

工程团队

_“如何根据我们的内部API进行身份验证？”_

OpenDocuments从您的GitHub仓库中提取答案 docs/auth.md，链接到相关的Swagger端点，并包含代码库中的代码示例——所有这些都在一个响应中。

# Index your repo and API docs
opendocuments index ./docs
opendocuments connector sync github
opendocuments ask "How does JWT token refresh work in our API?"

适用于运营和人力资源团队

_“东京办公室的远程工作政策是什么？”_

OpenDocuments可以搜索您的Confluence HR空间、Google Drive上的员工手册和最新的政策更新电子邮件，即使有些文件是韩语的，有些是英语的。

opendocuments ask "도쿄 오피스 원격 근무 정책이 뭐야?" --profile precise
# Cross-lingual search finds both Korean and English documents

面向产品经理

_“比较v2.0和v3.0的功能规格”_

OpenDocuments分解问题，搜索两个版本的规范，并给出一个结构化的比较表——引用每个源文档。

人工智能辅助开发（MCP）

使用OpenDocuments作为知识库 克劳德代码, 光标，或任何与MCP兼容的AI工具：

{
  "mcpServers": {
    "opendocuments": {
      "command": "opendocuments",
      "args": ["start", "--mcp-only"]
    }
  }
}

现在，您的AI编码助手可以在编写代码时搜索您组织的整个文档语料库。

用于自托管知识库

在您自己的基础设施上部署。您的数据 永远不要离开你的网络 当通过Ollama使用本地LLM时。没有云依赖，没有供应商锁定，没有订阅费。

docker compose --profile with-ollama up -d
# Everything runs locally: LLM, embeddings, vector search, web UI

______________________________________________________________________

快速开始

1.安装

npm install -g opendocuments

2.初始化

opendocuments init

交互式向导将：

• 检测您的硬件（CPU、RAM）并推荐最佳LLM
• 让你在两者之间做出选择 本地 （Ollama）或 云 （OpenAI、Claude、Gemini、Grok）模型
• 自动检测Ollama 并主动提出自动提取缺失的模型
• 验证云API密钥 保存之前
• 选择插件预设： Developer, Enterprise, All，或 Custom
• 生成 opendocuments.config.ts 和 .env （API密钥自动加载）

3.开始

opendocuments start

打开 http://localhost:3000 --您将看到一个聊天UI、文档管理器和管理仪表板。

第一次？ 如果Ollama不跑，你会看到一个清晰的 降阶模式 带有逐步修复说明的横幅。跑 opendocuments doctor 用于全面诊断。

4.为您的文档建立索引

# Index a local directory (recursively finds all supported files)
opendocuments index ./docs

# Watch mode: auto-reindex when files change
opendocuments index ./docs --watch

# Or drag-and-drop files in the Web UI

5.提问

opendocuments ask "What's our deployment process?"

______________________________________________________________________

运作原理

    Your Documents                    OpenDocuments                     You
    ─────────────                    ──────────────                    ───

    GitHub repos ──┐
    Notion pages ──┤                ┌─────────────┐
    Google Drive ──┤  ── Ingest ──► │ Parse        │
    Confluence   ──┤                │ Chunk        │     "How does
    S3 buckets   ──┤                │ Embed        │      auth work?"
    Swagger specs──┤                │ Store        │          │
    Local files  ──┤                └──────┬───────┘          │
    Web pages    ──┘                       │                  ▼
                                    ┌──────┴───────┐  ┌─────────────┐
                                    │  SQLite      │  │ RAG Engine  │
                                    │  (metadata)  │◄─┤ Search      │
                                    │              │  │ Rerank      │
                                    │  LanceDB     │  │ Generate    │
                                    │  (vectors)   │  │ Cite sources│
                                    └──────────────┘  └──────┬──────┘
                                                             │
                                                             ▼
                                                      "Auth uses JWT
                                                       tokens with
                                                       refresh flow.
                                                       [Source: auth.md]"

RAG管道

1. 意图分类 --了解您是在询问代码、概念、数据，还是想要进行比较
2. 查询分解 --将复杂问题分解为子查询，以便更好地检索
3. 跨语言搜索 --无论查询语言如何，都能查找韩语和英语的文档
4. 混合搜索 --通过互易秩融合将密集向量搜索（语义）与FTS5稀疏搜索（关键字）相结合
5. 重新排序 --按关键字重叠和基于模型的相关性对结果进行评分
6. 置信度评分 --当不确定答案时，告诉你
7. 幻觉守卫 --验证每个句子是否基于检索到的来源
8. 三层缓存 --L1查询缓存（5分钟），L2嵌入缓存（24小时），L3网络搜索缓存（1小时）

______________________________________________________________________

支持的文件格式

回退链：如果解析器失败，下一个解析器会自动尝试：

parserFallbacks: {
  '.pdf': ['@opendocuments/parser-pdf', '@opendocuments/parser-ocr'],
}

______________________________________________________________________

数据源

______________________________________________________________________

模型提供者

云提供商

本地模型（通过Ollama）

嵌入模型

自动推荐

opendocuments init 检测您的硬件并推荐最佳型号：

______________________________________________________________________

三种使用方法

1.Web用户界面

功能齐全的仪表板位于 http://localhost:3000:

键盘快捷键: Cmd+K 打开“命令选项板”。 Cmd+1-5 在页面之间导航。

2.CLI

面向高级用户和自动化的17个命令：

# Ask questions
opendocuments ask "What's the deploy process?"
opendocuments ask                              # Interactive REPL mode
opendocuments search "auth middleware" --top 10 # Vector search, no LLM

# Manage documents
opendocuments index ./docs --watch    # Index + auto-reindex on changes
opendocuments document list           # See all indexed docs
opendocuments document delete     # Soft-delete

# Manage connectors
opendocuments connector sync          # Sync all connectors
opendocuments connector status        # Check sync status

# Pipe support for scripting
cat README.md | opendocuments ask "Summarize this" --stdin
opendocuments ask "List endpoints" --json | jq '.sources[].sourcePath'

# Administration
opendocuments doctor                  # Health check
opendocuments auth create-key --name "ci-bot" --role member
opendocuments export --output ./backup

3.MCP服务器

19个用于人工智能辅助工作流程的工具。适用于Claude Code、Cursor、Windsurf和任何MCP客户端。

opendocuments start --mcp-only

然后，您的AI助手可以：

• 编码时搜索组织的文档
• 创建新文件时为其建立索引
• 检查文档状态和连接器健康状况
• 查询配置

______________________________________________________________________

RAG配置文件

| | fast | balanced | precise | |--|--------|------------|-----------| | 速度 |~1s|~3s|~5s+| | 搜索深度 |10个文档|20个文档|50个文档| | 语义组块 |On | On | On| | 重新排序 |关闭|打开|打开| | 交叉编码器 |关闭|关闭|打开| | 跨语言 |关闭|韩语+英语|韩语+英文| | 上下文前缀 |关闭|打开|打开| | 多查询扩展 |关闭| 3次释义| 5次释义| | 海德 |关闭|关闭|打开| | 父文档检索 |关闭|打开|打开| | 块状增强 （命题/HQ）|关闭|关闭|打开| | 查询分解 |Off | Off |拆分复杂查询| | 网络搜索 |关闭|本地结果较弱时回退|始终合并| | 幻觉守卫 |关闭|检查电源接地|严格模式（注释未验证）| | 最佳 |快速查找，8B本地模型|日常使用，14B+模型|关键问题，云LLM|

随时切换：CLI标志(--profile precise)、Web UI切换或配置文件。

检索质量

OpenDocuments提供了一个重新设计的RAG管道，具有结构保持分块、上下文检索、HyDE+多查询+父文档检索、命题增强和交叉编码器重排序器——所有这些都通过上表进行配置文件门控。看 查看完整的添加列表。

使用评估工具对您自己的数据集进行基准测试：

cd packages/core && npx tsx tests/_fixtures/run-eval.ts

报告的指标：hit@3, hit@5先生，nDCG@5--按意图和总计。

______________________________________________________________________

安全

个人模式（默认）

零配置。没有身份验证。仅限本地主机。只是工作。

团队模式

// opendocuments.config.ts
export default defineConfig({ mode: 'team' })

______________________________________________________________________

配置

// opendocuments.config.ts
import { defineConfig } from 'opendocuments-core'

export default defineConfig({
  workspace: 'my-team',
  mode: 'personal',

  model: {
    provider: 'ollama',
    llm: 'qwen3.5:27b',
    embedding: 'bge-m3',
  },

  rag: { profile: 'balanced' },

  connectors: [
    { type: 'github', repo: 'org/repo', token: process.env.GITHUB_TOKEN },
    { type: 'notion', token: process.env.NOTION_TOKEN },
    { type: 'web-crawler', urls: ['https://docs.example.com'] },
  ],

  plugins: ['@opendocuments/parser-pdf', '@opendocuments/parser-docx'],

  security: {
    dataPolicy: {
      autoRedact: { enabled: true, patterns: ['email', 'phone', 'credit-card'] },
    },
    audit: { enabled: true },
  },

  storage: { db: 'sqlite', vectorDb: 'lancedb', dataDir: '~/.opendocuments' },
})

______________________________________________________________________

Docker部署

# Basic (cloud LLM)
docker compose up -d

# With local LLM (Ollama)
docker compose --profile with-ollama up -d

# With .env file for API keys
docker compose --env-file .env up -d

Docker镜像包括所有包和插件。数据保存在命名卷中。安装您的配置：

docker run -v ./opendocuments.config.ts:/app/opendocuments.config.ts \
  -v opendocuments-data:/data -p 3000:3000 opendocuments

______________________________________________________________________

插件开发

创建自定义解析器、连接器或模型提供程序：

opendocuments plugin create my-parser --type parser
cd my-parser
npm install
npm run test
npm run dev       # Watch mode
opendocuments plugin publish  # Publish to npm

四种插件类型： parser, connector, model, middleware每个都有一个带生命周期钩子的类型化接口(setup, teardown, healthCheck, metrics).

社区插件遵循命名约定： opendocuments-plugin-*

看 贡献.md 获取完整的插件开发指南。

______________________________________________________________________

TypeScript SDK

import { OpenDocumentsClient } from '@opendocuments/client'

const client = new OpenDocumentsClient({
  baseUrl: 'http://localhost:3000',
  apiKey: 'od_live_...',
})

const result = await client.ask('How does auth work?')
console.log(result.answer)    // "Auth uses JWT tokens with..."
console.log(result.sources)   // [{ sourcePath: 'docs/auth.md', score: 0.92 }]
console.log(result.confidence) // { level: 'high', score: 0.87 }

______________________________________________________________________

可嵌入小部件

将聊天小部件添加到您的内部工具中：

  OpenDocuments.widget({
    server: 'http://localhost:3000',
    apiKey: 'od_live_...',
    workspace: 'public-docs',
  })

______________________________________________________________________

发展

git clone https://github.com/joungminsung/OpenDocuments.git
cd OpenDocuments
npm run setup    # Install + build (one command)
npm run test     # 51 test suites, ~300 tests
npm run dev      # Watch mode

建筑

看 贡献.md 获取约定、测试模式和插件开发指南。

______________________________________________________________________

文档

______________________________________________________________________

许可证

麻省理工学院