ECLAIRE

专注于隐私的 AI 助手，专为你的数据打造

_{点击在 YouTube 上观看}

功能 • 安装 • 选择模型 • 架构 • 开发 • 贡献 • 文档 • API

---

⚠️ 重要提示

[!IMPORTANT]
预发布 / 开发状态
Eclaire 目前处于预发布阶段，并正在积极开发中。
请预期频繁更新、破坏性变更以及不断演进的 API 和配置。
如果你部署了它，请务必定期备份你的数据，并在升级前仔细阅读发布说明。

[!WARNING]
安全警告
切勿将 Eclaire 直接暴露在公共互联网上。
本项目设计为以隐私和安全为核心进行自托管，但并未针对直接暴露进行加固。

我们强烈建议将其置于额外的安全层之后，例如：

• Tailscale 或其他私有网络/VPN
• Cloudflare Tunnels
• 带身份验证的反向代理

---

描述

Eclaire 是一个以本地优先（local-first）、开源的 AI 系统，可跨任务、笔记、文档、照片、书签等组织信息、回答问题并实现自动化。

目前已有大量框架和库支持各种 AI 能力；但很少有能提供完整产品体验，让用户真正高效完成任务的解决方案。Eclaire 将经过验证的构建模块整合为一个连贯、注重隐私的解决方案，你可以自行运行。

随着 AI 的快速普及，人们越来越需要替代封闭生态和托管模型的方案，尤其是处理个人、私密或敏感数据时。

• 自托管（Self-hosted） – 完全在你的硬件上运行，使用本地模型和本地数据存储
• 统一数据（Unified data） – AI 可在此处查看并关联所有内容
• AI 驱动（AI-powered） – 支持内容理解、搜索、分类、OCR（光学字符识别）和自动化
• 开源（Open source） – 透明、可扩展、社区驱动

v0.6.0 新特性

• 统一部署：前端 + 后端 + 工作进程可在单个容器中运行
• 简化自托管 – 新增一键式 setup.sh 流程，以及简化的 compose.yaml
• 更好的 AI 支持 – 新增视觉模型（包括 Qwen3-VL）、llama.cpp 路由器、改进的 MLX 支持
• 现代化前端 – 从 Next.js 迁移至 Vite + TanStack Router
• SQLite 支持：除 Postgres 外，新增对 SQLite 数据库的完整支持，适用于更轻量的工作负载
• 数据库队列模式：支持使用 Postgres 或 SQLite 进行任务处理，无需 Redis/BullMQ
• 全新管理 CLI – 可通过命令行管理你的实例

完整详情请参阅 CHANGELOG。

功能

• 跨平台：支持 macOS、Linux 和 Windows。
• 默认私有：默认情况下所有 AI 模型均在本地运行，所有数据均存储在本地。
• 统一数据：跨任务、笔记、文档、照片、书签等内容统一管理。
• AI 对话：基于你的内容上下文进行聊天；答案附带来源；支持流式输出和“思考”标记（thinking tokens）。
• AI 工具调用：助手具备多种工具，可用于搜索数据、打开内容、完成任务、添加评论、创建笔记等。
• 灵活部署：可作为单一统一容器运行，也可拆分为独立服务；支持 SQLite 或 Postgres；支持数据库队列或 Redis。（详见下方 架构 部分。）
• 完整 API：提供与 OpenAI 兼容的 REST 接口，支持会话令牌或 API 密钥。API 文档
• 模型后端：通过标准 OpenAI 兼容 API，支持 llama.cpp、vLLM、mlx-lm/mlx-vlm、LM Studio、Ollama 等。（详见 选择模型。）
• 模型支持：支持来自 Qwen、Gemma、DeepSeek、Mistral、Kimi 等的文本和视觉模型。（详见 选择模型。）
• 存储：所有资产（上传或生成）均存储于 Postgres 或文件/对象存储中。
• 集成：支持 Telegram（更多渠道即将推出）。
• 文档格式：PDF、DOC/DOCX、PPT/PPTX、XLS/XLSX、ODT/ODP/ODS、MD、TXT、RTF、Pages、Numbers、Keynote、HTML、CSV 等。
• 照片/图像格式：JPG/JPEG、PNG、SVG、WebP、HEIC/HEIF、AVIF、GIF、BMP、TIFF 等。
• 任务管理：可跟踪用户任务，或分配任务给 AI 助手完成；助手可为任务添加评论或将内容写入独立文档。
• 笔记：支持纯文本或 Markdown 格式，可链接到其他资产。
• 书签：自动抓取书签，并生成 PDF、可读版本及适合 LLM（大语言模型）处理的版本；对 GitHub 和 Reddit 提供特殊 API 和元数据处理。
• 组织管理：支持标签、置顶、标记、截止日期等功能，适用于所有资产类型。
• 硬件加速：充分利用 Apple MLX、NVIDIA CUDA 等平台特定优化。
• 移动端与 PWA：支持安装为 PWA；通过 iOS 快捷指令（Shortcuts）支持 iPhone 和 Apple Watch；通过 Tasker/MacroDroid 支持 Android。

典型使用场景

• 使用 Apple Watch（或其他智能手表）口述笔记。
• 保存稍后阅读的书签；生成干净的“可读”版本和 PDF 版本。
• 为网站创建可读版本和 PDF 版本。
• 从照片和文档图像中提取文字（OCR，光学字符识别）。
• 批量将 HEIC 格式的照片转换为 JPG。
• 利用 AI 分析、分类并搜索文档和照片。
• 将文档和书签转换为适合大语言模型（LLM）处理的文本/Markdown 格式。
• 从手机、平板或桌面设备保存感兴趣的内容（网页、照片、文档等）。
• 让 AI 在你的数据中查找或总结信息。
• 安排自动化任务（例如：“每周一早上，总结我本周的任务。”）。
• 通过网页、移动端、Telegram 等渠道与 AI 聊天。
• 在本地模型上私密处理敏感信息（如银行、健康等数据）。
• 批量上传桌面文件，让 AI 自动整理和打标签，清理桌面杂乱。
• 将 Google/Apple 等厂商的数据迁移到一个开放、可自托管且由你完全掌控的平台。

截图

安装

先决条件

• Docker 和 Docker Compose
• 本地 LLM（大语言模型）服务器 —— 推荐使用 llama.cpp

快速开始

mkdir eclaire && cd eclaire
curl -fsSL https://raw.githubusercontent.com/eclaire-labs/eclaire/main/setup.sh | sh

该脚本将：

1. 下载配置文件
2. 自动生成密钥（secrets）
3. 初始化数据库（PostgreSQL）

设置完成后：

# 1. 启动你的 LLM 服务器（在单独的终端中运行）
#    如果模型尚未缓存，首次运行时会自动下载
llama-server -hf unsloth/Qwen3-14B-GGUF:Q4_K_XL --ctx-size 16384 --port 11500
llama-server -hf unsloth/gemma-3-4b-it-qat-GGUF:Q4_K_XL --ctx-size 16384 --port 11501

# 2. 启动 Eclaire
docker compose up -d

打开 http://localhost:3000 并点击“注册”以创建账户。

如需使用其他 AI 提供商和模型，请参阅 AI 模型配置。

配置

配置文件位于两个位置：

• .env —— 存放密钥、数据库设置、端口等
• config/ai/ —— LLM 提供商的 URL 和模型定义

停止服务

docker compose down

模型选择

Eclaire 使用 AI 模型实现两类功能：

• 后端（Backend）：驱动聊天助手（需要良好的工具调用能力）
• 工作器（Workers）：处理文档和图像（需要视觉能力）

Apple Silicon：Mac 用户可利用 MLX 实现优化的本地推理。详情请参阅 配置指南。

使用 CLI 管理模型：

docker compose run --rm eclaire model list

有关详细设置和模型推荐，请参阅 AI 模型配置。

架构

Eclaire 采用模块化架构，前端、后端 API、后台工作器和数据层之间职责清晰。

📋 查看详细架构图 →

核心组件

• 前端：基于 Vite 的 Web 应用，使用 React 19、TanStack Router 和 Radix UI
• 后端 API：基于 Node.js/Hono 的 REST API 服务器
• 后台工作器：负责任务处理和调度（默认与后端统一运行）
• 数据层：推荐使用 PostgreSQL，也可使用 SQLite 进行持久化；任务队列使用数据库或 Redis
• AI 服务：本地 LLM 后端（如 llama.cpp、MLX、LM Studio 等）用于推理；Docling 用于文档处理
• 外部集成：通过 GitHub 和 Reddit API 获取书签内容

路线图

• 支持更多数据源和集成
• 更强大的全文索引和搜索功能
• 更好的可扩展性和插件系统
• 增强 AI 能力和模型支持
• 为模型和内容处理管道添加评估（Evals）
• 加强安全性和系统加固
• 实现社区最高票请求的功能

开发

适用于希望从源码构建的贡献者。

额外先决条件

除了 Docker 和 LLM 服务器外，你还需要：

• Node.js ≥ 24，并启用 corepack
• pnpm（通过 corepack 管理）

文档/图像处理工具：

macOS:

brew install --cask libreoffice
brew install poppler graphicsmagick imagemagick ghostscript libheif

Ubuntu/Debian:

sudo apt-get install libreoffice poppler-utils graphicsmagick imagemagick ghostscript libheif-examples

设置

git clone https://github.com/eclaire-labs/eclaire.git
cd eclaire
corepack enable
pnpm setup:dev
pnpm dev

访问应用：

• 前端：http://localhost:3000
• 后端：http://localhost:3001/health

本地构建 Docker 镜像

如需构建并测试自定义 Docker 镜像：

./scripts/build.sh
docker compose -f compose.yaml -f compose.dev.yaml -f compose.local.yaml up -d

贡献

我们 💙 欢迎各种贡献！请阅读贡献指南。

安全

请参阅 SECURITY.md 了解我们的安全策略。

遥测

Eclaire 代码中不应包含任何遥测功能，尽管第三方依赖项可能包含。如发现此类情况，请告知我们。

社区与支持

问题反馈：GitHub Issues

Eclaire 快速上手指南

Eclaire 是一个注重隐私的开源 AI 助手，支持本地运行，可统一管理任务、笔记、文档、图片、书签等数据，并通过本地大模型实现智能问答与自动化。

---

环境准备

系统要求

• 支持 macOS、Linux 和 Windows
• 推荐使用 Apple Silicon（M1/M2/M3）或 NVIDIA GPU 以获得硬件加速

前置依赖

• Docker 和 Docker Compose
• 本地 LLM 服务（推荐 llama.cpp）
• （可选）如需处理文档/图片，还需安装以下工具：
  • macOS:

    brew install --cask libreoffice
    brew install poppler graphicsmagick imagemagick ghostscript libheif
    

  • Ubuntu/Debian:

    sudo apt-get install libreoffice poppler-utils graphicsmagick imagemagick ghostscript libheif-examples
    

💡 国内用户建议配置 Docker 镜像加速器（如阿里云、中科大镜像源）以提升拉取速度。

---

安装步骤

1. 创建项目目录并运行一键安装脚本：

   mkdir eclaire && cd eclaire
   curl -fsSL https://raw.githubusercontent.com/eclaire-labs/eclaire/main/setup.sh | sh
   

   脚本将自动：

   • 下载配置文件
   • 生成密钥
   • 初始化 PostgreSQL 数据库

2. 启动本地 LLM 服务（在单独终端中运行，模型首次使用时会自动下载）：

   # 示例：启动两个本地模型（文本 + 视觉）
   llama-server -hf unsloth/Qwen3-14B-GGUF:Q4_K_XL --ctx-size 16384 --port 11500
   llama-server -hf unsloth/gemma-3-4b-it-qat-GGUF:Q4_K_XL --ctx-size 16384 --port 11501
   

3. 启动 Eclaire 服务：

   docker compose up -d
   

4. 打开浏览器访问 http://localhost:3000，点击 “Sign up” 创建账户即可开始使用。

⚠️ 注意：请勿将 Eclaire 直接暴露在公网。建议通过 Tailscale、Cloudflare Tunnel 或带认证的反向代理访问。

---

基本使用

最简使用流程

1. 上传内容：在 Web 界面上传文档（PDF、Word 等）、图片（JPG、PNG 等）或添加书签。
2. 与 AI 对话：在聊天界面提问，例如：
   • “总结我上周的笔记”
   • “找出所有包含发票的图片”
   • “把这张 HEIC 照片转成 JPG”
3. 查看结果：AI 会基于你的私有数据回答，并标注信息来源。

管理模型（可选）

列出当前可用模型：

docker compose run --rm eclaire model list

更多模型配置（如使用 Ollama、LM Studio 或 MLX）请参考官方文档：AI Model Configuration

---

📌 提示：Eclaire 目前处于预发布阶段，升级前请务必备份数据并查阅 CHANGELOG。