Skip to main content
安装应该很无聊；把戏剧性留给你的第一个查询。

​
1. 动机

一个多后端数据项目已经有足够多的活动部件。HeavenBase 保持基础安装精简，只在工作区真正需要时再添加提供商与数据库 extra。 最短的受支持路径是 pip install heavenbase，然后运行一次 hb setup。后续章节帮助你选择环境、可选 extra 与验证路径，而不把安装变成架构设计。

​
2. 系统要求

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

​
3. 推荐软件

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

​
4. 安装

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

​
4.1. 从 PyPI 安装

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

​
4.2. 可选 Extras

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

​
5. 从源码安装

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

​
6. 初始化

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

​
7. 验证安装

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

​
总结

  • 先安装基础包，只为实际使用的集成添加 extra。
  • 运行一次 hb setup，初始化 Context 所拥有的配置与工作区元数据。
  • 配置提供商或开始工作坊前，先验证 CLI 版本。

​
进一步探索

下一步：