Ragtime是什么？2026年自托管RAG API与MCP服务器深度解析

Ragtime 是一个功能强大的开源平台，它将检索增强生成（RAG）能力与模型上下文协议（MCP）服务器相结合。其核心设计理念是作为一个自托管的、兼容 OpenAI 的 API，能够将您的本地知识库无缝集成到现有的 LLM 客户端和 AI 编程助手中。通过提供内置的 Web UI、隔离的工作空间以及丰富的工具集，Ragtime 旨在成为连接大型语言模型与您真实工作环境的桥梁。

核心特性

• 内置聊天界面：包含工具可视化、交互式图表和 DataTables，无需外部客户端。
• 工作空间：在隔离的运行时会话中运行的实时预览；共享链接使用简洁的公共 URL（/{owner}/{slug}），并可选择密码保护的全页面访问。
• MCP 服务器：支持 HTTP Streamable 和 stdio 传输，将工具暴露给 Claude Desktop、VS Code Copilot、Cursor 和 JetBrains IDE，并支持身份验证。
• 兼容 OpenAI 的 API：提供支持流式传输的 /v1/chat/completions 端点，可与 OpenWebUI、Continue 及任何 OpenAI 客户端协同工作。
• 双向量存储：为上传/Git 索引选择 FAISS 或 pgvector；为 schema/PDM 和可选的文件系统索引使用 pgvector。
• 工具安全性：通过允许列表模式、LIMIT 强制执行、Odoo 代码验证和可选的写操作标志来防止 SQL 注入。

架构概览

Ragtime 的架构围绕一个中心服务构建，该服务协调工具执行、上下文检索和 LLM 交互。其设计旨在实现模块化和可扩展性。

flowchart LR
  Tools["Tools<br>(SQL, SSH, Odoo)"] -->|tool runs + results| Ragtime
  Context["Knowledge Sources<br>(FAISS, pgvector)"] -->|retrieved context| Ragtime
  LLM["LLM Provider<br>(OpenAI, Anthropic, Ollama)"] -->|LLM API| Ragtime

  subgraph Ragtime["Ragtime"]
    direction TB
    API["/v1/chat/completions"]
    MCP["/mcp"]
    UI["Web UI"]
  end

  Ragtime -->|chat responses| Clients["Clients<br>(OpenWebUI, Claude, VS Code)"]
  Clients -->|chat queries| Ragtime

  style Ragtime fill:#1a365d,stroke:#3182ce,stroke-width:3px,color:#fff

工作空间：智能开发沙盒

工作空间是 Ragtime 的智能开发沙盒。每个工作空间都集成了文件、对话、选定的基础设施工具以及一个隔离的运行时预览会话。可以将其理解为类似 Replit 的沙盒环境，但通过 Ragtime 工具（SQL、SSH、Odoo、文件系统索引器等）连接到您的真实环境，从而使智能体能够在实时上下文中完成有用的工作。

• 预览仅在运行时有效，并从会话管理的开发服务器代理。
• 公共共享使用直接路由（/{owner}/{slug} 和 /shared/{token}），令牌链接会重定向到规范的 slug URL。
• 密码保护的共享通过服务器端的全页面提示进行处理。

向量存储抽象层

Ragtime 使用两种向量后端：FAISS（内存式，启动时加载）和 pgvector（PostgreSQL，持久化）。上传和 Git 索引使用统一的索引器，并可以选择任一后端。

FAISS 索引在启动时加载到内存中；pgvector 索引保留在 PostgreSQL 中，并使用余弦相似度搜索。嵌入提供者（OpenAI 或 Ollama）在设置中配置一次，并应用于所有索引类型。在初始索引后更换嵌入模型或维度需要完全重新索引。

快速入门指南

先决条件

• Docker 和 Docker Compose
• 包含您配置的 .env 文件

设置步骤

1. 创建环境文件：创建一个名为 .env 的文件，内容如下（您也可以从 .env.example 完整示例中复制）：

   # =============================================================================
   # Ragtime RAG API - Environment Configuration
   # =============================================================================
   # Copy this file to .env and fill in your values
   
   # -----------------------------------------------------------------------------
   # Database Configuration
   # -----------------------------------------------------------------------------
   POSTGRES_PASSWORD=changeme
   
   # -----------------------------------------------------------------------------
   # Authentication Configuration
   # -----------------------------------------------------------------------------
   LOCAL_ADMIN_USER=admin
   LOCAL_ADMIN_PASSWORD=changeme_admin
   
   # -----------------------------------------------------------------------------
   # Server Configuration
   # -----------------------------------------------------------------------------
   PORT=8000
   ALLOWED_ORIGINS=*
   
   # -----------------------------------------------------------------------------
   # Security Configuration
   # -----------------------------------------------------------------------------
   # Generate with: openssl rand -base64 32
   API_KEY=
   

2. 创建 docker-compose.yml 文件：创建一个包含以下内容的 docker-compose.yml 文件：

   services:
     ragtime-db:
       image: pgvector/pgvector:pg18
       container_name: ragtime-db
       restart: unless-stopped
       environment:
         POSTGRES_USER: ragtime
         POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
         POSTGRES_DB: ragtime
       volumes:
         - ragtime-db-data:/var/lib/postgresql
       networks:
         - ragtime-network
   
     ragtime:
       image: hub.docker.visnovsky.us/library/ragtime:main
       container_name: ragtime
       restart: unless-stopped
       ports:
         - "${PORT:-8000}:8000"
       env_file:
         - .env
       environment:
         DATABASE_URL: postgresql://ragtime:${POSTGRES_PASSWORD}@ragtime-db:5432/ragtime
       volumes:
         - ./data:/data
       networks:
         - ragtime-network
       depends_on:
         - ragtime-db
   
   networks:
     ragtime-network:
       driver: bridge
   
   volumes:
     ragtime-db-data:
   

3. 启动应用程序：

   docker compose up -d
   

4. 访问应用程序：

   • Web 界面: http://localhost:8000
   • API 文档: http://localhost:8000/docs

   默认凭据：admin / （在 .env 中通过 LOCAL_ADMIN_PASSWORD 设置）

工具配置

在将 Ragtime 连接到 MCP 客户端之前，需要在 Ragtime Web UI 中配置工具，使其准备就绪：

1. 在 http://localhost:8000 打开 Web UI，使用您的管理员账户登录。
2. 导航到 工具 选项卡。
3. 点击 添加工具 并选择工具类型（PostgreSQL、Odoo、SSH、文件系统索引器等）。
4. 为每个工具填写连接详细信息（主机名、凭据、数据库名、路径等）。
5. 使用内置的测试按钮验证每个工具的连接。

只有通过健康检查的工具才会暴露给聊天和 MCP 客户端。请在此处配置并验证您的工具，然后再继续下面的 MCP 集成 部分。

创建索引

索引器 UI（http://localhost:8000，索引 选项卡）支持多种索引类型：

作业异步运行，进度流式传输到 UI。

模型上下文协议 (MCP) 集成

Ragtime 通过 模型上下文协议 暴露其工具，允许 AI 编程助手与您的数据库交互、执行 shell 命令以及搜索您已索引的代码库。

可用的 MCP 工具

工具根据您在 UI 中的配置动态暴露：

常见问题（FAQ）

Ragtime如何将本地知识集成到现有AI工具中？

Ragtime通过兼容OpenAI的API和MCP服务器实现集成。它提供/v1/chat/completions端点支持流式传输，可与OpenWebUI、Continue等客户端协同工作；MCP服务器则通过HTTP/stdio传输将工具暴露给Claude Desktop、VS Code Copilot等IDE。

Ragtime的双向量存储有什么具体用途？

Ragtime支持FAISS和pgvector双向量存储：FAISS或pgvector用于上传/Git索引，pgvector用于schema/PDM和可选的文件系统索引。这种设计提供了灵活的存储选择，满足不同知识源的索引需求。

Ragtime的工作空间功能有什么安全特性？

工作空间提供隔离的运行时会话，共享链接使用简洁的公共URL格式（/{owner}/{slug}），并可选择密码保护的全页面访问。这确保了开发环境的安全隔离和可控的协作访问。