跳转到主要内容
TL;DR： 你只需要 pip install heavenbase && hb setup 。

​
1. 系统要求

HeavenBase 可在任何有 Python 的系统上运行——无需 GPU、机架或集群。
  • 操作系统：macOS、Linux、Windows。已在 Windows 11 与 macOS Sequoia 上测试。
  • Python：3.10 或更高。已在 Python 3.10 至 3.13 上测试。
  • 硬件：普通消费级硬件即可。部分可选依赖（通过 Ollama 或 LM Studio 本地提供 LLM）可能有自己的硬件偏好，但 HeavenBase 本身很轻量。

​
2. 推荐软件

以下工具完全可选，但能让 HeavenBase 体验丰富得多：
  • Docker — 启动本地数据库（PostgreSQL、MySQL、Milvus 等）用于测试或生产。
  • Portkey 或 Bifrost — LLM 入口 (Gateway)，用于多 provider 的可观测性、缓存、故障转移与密钥管理。
  • Ollama 或 LM Studio — 本地运行 LLM 与嵌入模型。无需 API 密钥、无速率限制、完全私密。
HeavenBase 内置支持 16+ 数据库后端： 详见 数据库集成 与 向量数据库集成 的安装指南。

​
3. 安装

HeavenBase 支持多种包管理器。按你的工作流偏好选择。
HeavenBase 0.1.1.5 是当前 PyPI 发布版本。Conda-forge 包尚未发布；本版本请使用 pip、uv 或 Poetry。

​
3.1. 从 PyPI 安装

从下列任一包管理器选择： pip：
uv：
poetry：
Conda-forge：
Conda-forge 包尚未发布 0.1.1.5；当前版本请使用 pip、uv 或 Poetry。

​
3.2. 可选 Extras

按需安装额外数据库与开发依赖： pip：
uv：
poetry：
Conda-forge：
可选 extras 目前是 PyPI 包 extras。Conda-forge 包发布前，请使用 pip、uv 或 Poetry 安装 extras。

​
4. 从源码安装

克隆仓库并用你偏好的方式安装：
pip（可编辑安装，开发推荐）：
从源码安装全部 extras：
uv：
poetry：
conda：

​
5. 初始化

安装后运行一次 setup。它会创建全局配置存储、初始化 Capsule 注册表并注册默认工作区：
所有包数据位于 ~/.heavenbase/。更方便的是，随时用 hb pj %/ 查看路径，其中 % 映射到 heavenbase 全局根目录 ~/.heavenbase/。
hb setup --reset 会销毁所有配置、缓存数据与已注册工作区。此操作不可逆。仅在你打算从头开始时使用。

​
6. 验证安装

快速配置测试：
status 命令会打印解析后的 LLM preset、provider、model 与 gateway。开箱即用使用 system 与 chat preset，由 OpenRouter 上的 deepseek-v4-flash 支撑——无需改配置文件，只需在环境中设置 OPENROUTER_API_KEY 即可。 现在用 HeavenBase README 作为上下文，用默认 LLM 试一次对话：
接下来进入下一章：First LLM — 快速使用 LLM 进行对话、嵌入、会话与 Python API 调用。

​
进一步探索

下一步：