Utopia 是一个企业级世界模型，其核心是一个双时态知识图谱。它不仅记录事实，还记录事实的”世界时间”（何时为真）和”系统时间”（何时被系统获知），修正事实时不会覆盖旧版本，而是链接新版本，从而构建一条可审计、可追溯的证据链。它专为需要高可信度和强合规性的场景设计（如金融、法务、政企），区别于普通的RAG问答系统。

📦 第一步：环境准备

Utopia 的部署非常轻量，核心依赖只有一个 Rust 二进制文件和 PostgreSQL 数据库。

硬性要求：

  • Docker（推荐） 或 Rust 1.85+、Node.js 20+ 和 pnpm（用于源码开发）。
  • PostgreSQL：需要安装 pgvector 扩展（使用 Docker 部署会自动处理）。
  • 端口：确保 1516（默认 Web 端口）和 5432（数据库端口）未被占用。

🚀 第二步：快速部署（推荐）

最快捷的方式是使用官方提供的 Docker Compose 预构建镜像。

  1. 克隆项目：

    1
    2
    git clone https://github.com/deeplethe/utopia.git
    cd utopia

  2. 启动服务：
    使用 --profile app 会启动包括 Web 界面、后端服务和数据库在内的所有必需服务。

    1
    docker compose --profile app up -d

    该命令会拉取 ghcr.io/deeplethe/utopia 的预构建镜像，数据（如上传的文件和搜索索引）默认存储在 ./data 目录下，需要你自行备份。

  3. 访问与初始化：
    打开浏览器访问 http://localhost:1516。你注册的第一个账户将自动成为系统管理员，并会同时创建一个公共知识库。

⚙️ 第三步：配置模型与知识库

在开始使用之前，需要为 Utopia 配置大语言模型（LLM）和嵌入模型，因为它本身不提供模型，而是通过 API 与外部模型交互。

  1. 进入设置：登录后，在系统界面中找到 “Administration”（管理）或 “Settings”（设置）菜单。
  2. 配置模型端点：在 “Models” 或 “LLM” 配置部分，添加一个兼容 OpenAI API 的端点。你可以使用：
    • 云端服务：OpenAI、DeepSeek、Qwen（通义千问）、智谱 GLM 等。
    • 本地部署：Ollama、vLLM 等。这允许 Utopia 在完全离线的网络环境下运行。
  3. 选择模型：为**对话（Chat）和嵌入（Embedding）**分别选择你配置好的模型。
  4. 创建知识库：回到主界面，创建一个新的知识库（Knowledge Base），或直接使用初始化时创建的公共知识库。

🛠️ 第四步：核心配置（环境变量）

Utopia 的所有配置通过以 UTOPIA_ 为前缀的环境变量进行管理。你可以将项目根目录下的 .env.example 复制为 .env 并修改。

变量名 默认值 说明 生产环境建议
UTOPIA_DATABASE_URL postgres://utopia:utopia@localhost:5432/utopia PostgreSQL 连接字符串 必须修改为安全的数据库凭据
UTOPIA_JWT_SECRET dev-secret-change-me JWT 认证密钥 必须修改为一个强密码
UTOPIA_BIND_ADDR 0.0.0.0:1516 后端服务监听地址和端口 按需修改，注意防火墙设置
UTOPIA_OPEN_REGISTRATION true 是否允许开放注册 生产环境建议设为 false，仅允许首个管理员注册
UTOPIA_DATA_DIR data 存储上传文件和搜索索引的目录 建议挂载到持久化存储卷

重要安全提示：

  1. API 密钥存储：目前在 UI 中配置的 LLM API 密钥和数据库连接字符串是明文存储在 PostgreSQL 中的。在 1.0 版本之前，建议在可信的内网环境中运行。
  2. 版本升级：Utopia 目前处于 v0.1 阶段。数据库 Schema 会持续演进，且迁移仅向前兼容，不支持回滚。生产环境部署时，请通过 UTOPIA_IMAGE 固定特定版本，并务必在升级前备份数据库和 data 目录。

💻 第五步：本地开发（可选）

如果你希望进行二次开发或从源码启动，可以按照以下步骤：

  1. 启动数据库：

    1
    docker compose up -d db

  2. 运行后端（在项目根目录）：

    1
    cargo run -p utopia-server

    这会启动一个运行在 :1516 的后端服务，并自动执行数据库迁移。

  3. 运行前端：

    1
    2
    3
    cd web
    pnpm install
    pnpm dev

    前端开发服务器会运行在 http://localhost:5173，并将 /api 请求代理到后端。

🔭 下一步：探索核心能力

部署完成后，你可以开始探索 Utopia 的独特之处：

  • 知识摄取：上传 PDF、DOCX、PPTX、Markdown 等多种格式文档，或配置网页、RSS、GitHub、Jira 等数据源的定时同步。
  • 搜索与问答：体验融合了全文检索（Tantivy）和向量检索（pgvector）的混合搜索，回答会附带可点击的文献引用。
  • 本体论（Ontology）：系统内置了 schema.org、W3C Org、PROV-O 等本体包。新出现的术语会被计数，你可以确认并让其加入组织的共享词汇表。
  • 推理与冲突检测：系统能基于本体规则进行前向链推理，推导出新的事实，并能检测事实间的矛盾（如时间冲突、违反公理）。

Utopia 为构建可审计、可推理的企业知识中台提供了全新的基础。从 Docker 部署开始，你将能逐步体验到其双时态知识图谱的强大之处。