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

Ragtime: A Self-Hosted, OpenAI-Compatible RAG API and MCP Server

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

Ragtime is a powerful open-source platform that combines Retrieval-Augmented Generation (RAG) capabilities with a Model Context Protocol (MCP) server. Its core design philosophy is to serve as a self-hosted, OpenAI-compatible API that seamlessly integrates your local knowledge base into existing LLM clients and AI coding assistants. By offering a built-in Web UI, isolated workspaces, and a rich set of tools, Ragtime aims to bridge the gap between large language models and your real-world working environment.

核心特性

Core Features

• 内置聊天界面：包含工具可视化、交互式图表和 DataTables，无需外部客户端。

  Built-in Chat UI: Features tool visualization, interactive charts, and DataTables, eliminating the need for an external client.

• 工作空间：在隔离的运行时会话中运行的实时预览；共享链接使用简洁的公共 URL（/{owner}/{slug}），并可选择密码保护的全页面访问。

  Workspaces: Live previews run in isolated runtime sessions; shared links use clean public URLs (/{owner}/{slug}), with optional password-protected full-page access.

• MCP 服务器：支持 HTTP Streamable 和 stdio 传输，将工具暴露给 Claude Desktop、VS Code Copilot、Cursor 和 JetBrains IDE，并支持身份验证。

  MCP Server: Supports HTTP Streamable and stdio transports, exposing tools to Claude Desktop, VS Code Copilot, Cursor, and JetBrains IDEs with authentication.

• 兼容 OpenAI 的 API：提供支持流式传输的 /v1/chat/completions 端点，可与 OpenWebUI、Continue 及任何 OpenAI 客户端协同工作。

  OpenAI-Compatible API: Provides a streaming-capable /v1/chat/completions endpoint, compatible with OpenWebUI, Continue, and any OpenAI client.

• 双向量存储：为上传/Git 索引选择 FAISS 或 pgvector；为 schema/PDM 和可选的文件系统索引使用 pgvector。

  Dual Vector Store: Choose FAISS or pgvector for Upload/Git indexes; use pgvector for schema/PDM and optional filesystem indexing.

• 工具安全性：通过允许列表模式、LIMIT 强制执行、Odoo 代码验证和可选的写操作标志来防止 SQL 注入。

  Tool Security: SQL injection prevention via allowlist patterns, LIMIT enforcement, Odoo code validation, and an optional write-ops flag.

架构概览

Architecture Overview

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

Ragtime's architecture revolves around a central service that orchestrates tool execution, context retrieval, and LLM interactions. It is designed for modularity and extensibility.

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

工作空间：智能开发沙盒

Workspaces: Agentic Development Sandboxes

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

Workspaces are Ragtime's agentic development sandboxes. Each workspace combines files, conversations, selected infrastructure tools, and an isolated runtime preview session. Think of it as a Replit-style sandbox, but connected to your real environment through Ragtime tools (SQL, SSH, Odoo, filesystem indexers, and more), enabling agents to perform useful work with live context.

• 预览仅在运行时有效，并从会话管理的开发服务器代理。

  Previews are runtime-only and proxied from session-managed devservers.

• 公共共享使用直接路由（/{owner}/{slug} 和 /shared/{token}），令牌链接会重定向到规范的 slug URL。

  Public sharing uses direct routes (/{owner}/{slug} and /shared/{token}), with token links redirecting to canonical slug URLs.

• 密码保护的共享通过服务器端的全页面提示进行处理。

  Password-protected shares are handled server-side with a full-page prompt.

向量存储抽象层

Vector Store Abstraction

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

Ragtime uses two vector backends: FAISS (in-memory, loaded at startup) and pgvector (PostgreSQL, persistent). Upload and Git indexes use a unified indexer and can use either backend.

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

FAISS indexes are loaded into memory at startup; pgvector indexes stay in PostgreSQL and use cosine similarity search. The embedding provider (OpenAI or Ollama) is configured once in Settings and applies to all index types. Swapping the embedding model or dimensions after initial indexing requires a full re-index.

快速入门指南

Quick Start Guide

先决条件

Prerequisites

• Docker 和 Docker Compose

  Docker and Docker Compose

• 包含您配置的 .env 文件

  A .env file with your configuration

设置步骤

Setup Steps

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

   Create environment file: Create a file named .env with the following content (you can also copy from the full example in .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 文件：

   Create docker-compose.yml file: Create a docker-compose.yml file with the following content:

   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. 启动应用程序：

   Start the application:

   docker compose up -d
   

4. 访问应用程序：

   Access the application:

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

     • Web UI: http://localhost:8000
     • API docs: http://localhost:8000/docs

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

   Default credentials: admin / (set via LOCAL_ADMIN_PASSWORD in .env)

工具配置

Tool Configuration

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

Before connecting Ragtime to MCP clients, configure tools in the Ragtime web UI so they are ready for use:

1. 在 http://localhost:8000 打开 Web UI，使用您的管理员账户登录。

   Open the web UI at http://localhost:8000 and log in with your admin account.

2. 导航到 工具 选项卡。

   Navigate to the Tools tab.

3. 点击 添加工具 并选择工具类型（PostgreSQL、Odoo、SSH、文件系统索引器等）。

   Click Add Tool and select the tool type (PostgreSQL, Odoo, SSH, filesystem indexer, etc.).

4. 为每个工具填写连接详细信息（主机名、凭据、数据库名、路径等）。

   Fill in connection details (hostnames, credentials, database names, paths) for each tool.

5. 使用内置的测试按钮验证每个工具的连接。

   Use the built-in test button to verify each tool connection.

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

Only tools that pass their health checks are exposed to chat and MCP clients. Configure and verify your tools here before following the MCP Integration section below.

创建索引

Creating Indexes

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

The Indexer UI (http://localhost:8000, Indexes tab) supports multiple index types:

方法	向量存储	存储位置	使用场景
上传 (zip/tar)	FAISS 或 pgvector	FAISS: data/indexes/<name>/ pgvector: filesystem_embeddings 表	静态代码库、文档快照
Git 克隆	FAISS 或 pgvector	FAISS: data/indexes/<name>/ pgvector: filesystem_embeddings 表	仓库（支持可选的私有令牌认证）
文件系统	pgvector	filesystem_embeddings 表	实时 SMB/NFS 共享、Docker 卷、本地路径：支持增量重新索引
Schema	pgvector	schema_embeddings 表	从 PostgreSQL/MSSQL/MySQL 工具自动生成
PDM	pgvector	pdm_embeddings 表	通过 SQL Server 获取 SolidWorks PDM 元数据

Method	Vector Store	Storage	Use Case
Upload (zip/tar)	FAISS or pgvector	FAISS: data/indexes/<name>/ pgvector: filesystem_embeddings table	Static codebases, documentation snapshots
Git Clone	FAISS or pgvector	FAISS: data/indexes/<name>/ pgvector: filesystem_embeddings table	Repositories with optional private token auth
Filesystem	pgvector	filesystem_embeddings table	Live SMB/NFS shares, Docker volumes, local paths: incremental re-index
Schema	pgvector	schema_embeddings table	Auto-generated from PostgreSQL/MSSQL/MySQL tools
PDM	pgvector	pdm_embeddings table	SolidWorks PDM metadata via SQL Server

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

Jobs run async with progress streaming to the UI.

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

Model Context Protocol (MCP) Integration

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

Ragtime exposes its tools via the Model Context Protocol, allowing AI coding assistants to interact with your databases, execute shell commands, and search your indexed codebases.

可用的 MCP 工具

Available MCP Tools

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

Tools are dynamically exposed based on what you configure in the UI:

工具类型	输入模式
postgres	{query, reason}
mssql	{query, reason}
mysql	{query, reason}
odoo_shell	{code, reason}
ssh_shell	{command, reason}
filesystem_indexer	{query, max_results}
knowledge_search	{query, index_name}
schema_search	{prompt, limit}
git_history	{action, ...}

Tool Type	Input Schema
postgres	{query, reason}
mssql	{query, reason}
mysql	{query, reason}
odoo_shell	{code, reason}
ssh_shell	{command, reason}
filesystem_indexer	{query, max_results}
knowledge_search	`{query, index_name

常见问题（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}），并可选择密码保护的全页面访问。这确保了开发环境的安全隔离和可控的协作访问。