> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装

> HeavenBase 的系统要求、推荐软件、安装与首次运行验证。

<Note>
  ***TL;DR：** 你只需要 `pip install heavenbase && hb setup` 。*
</Note>

<br />

## 1. 系统要求

HeavenBase 可在任何有 Python 的系统上运行——无需 GPU、机架或集群。

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

<br />

## 2. 推荐软件

以下工具完全可选，但能让 HeavenBase 体验丰富得多：

* **[Docker](https://www.docker.com/)** — 启动本地数据库（PostgreSQL、MySQL、Milvus 等）用于测试或生产。
* **[Portkey](https://portkey.ai/)** 或 **[Bifrost](https://github.com/RubikSQL/Bifrost)** — LLM 入口 (Gateway)，用于多 provider 的可观测性、缓存、故障转移与密钥管理。
* **[Ollama](https://ollama.com/)** 或 **[LM Studio](https://lmstudio.ai/)** — 本地运行 LLM 与嵌入模型。无需 API 密钥、无速率限制、完全私密。

HeavenBase 内置支持 **16+ 数据库后端**：

| Category          | Backends                                                                      |
| ----------------- | ----------------------------------------------------------------------------- |
| **SQL databases** | SQLite, PostgreSQL, MySQL, DuckDB, OceanBase, MsSQL, Oracle, Trino, StarRocks |
| **Vector stores** | Milvus, LanceDB, Chroma, Pinecone, pgvector                                   |
| **Search / text** | Elasticsearch                                                                 |

详见 [数据库集成](/zh/integrations/databases) 与 [向量数据库集成](/zh/integrations/vector-databases) 的安装指南。

<br />

## 3. 安装

HeavenBase 支持多种包管理器。按你的工作流偏好选择。

<Info>
  HeavenBase **0.1.1.5** 是当前 PyPI 发布版本。Conda-forge 包尚未发布；本版本请使用 pip、uv 或 Poetry。
</Info>

<br />

### 3.1. 从 PyPI 安装

从下列任一包管理器选择：

**pip：**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install heavenbase
```

**uv：**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv pip install heavenbase
```

**poetry：**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poetry add heavenbase
```

**Conda-forge：**

<Note>
  Conda-forge 包尚未发布 0.1.1.5；当前版本请使用 pip、uv 或 Poetry。
</Note>

<br />

### 3.2. 可选 Extras

按需安装额外数据库与开发依赖：

| Extra     | Contents                                                                 | When to use            |
| --------- | ------------------------------------------------------------------------ | ---------------------- |
| `dev`     | 测试、lint 与贡献者工具链                                                          | 贡献者工作流                 |
| `interop` | Pydantic、pandas、pyarrow 与 SQLAlchemy 互操作辅助                               | 与外部系统的数据互操作            |
| `daft`    | 面向 dataframe 工作负载的 Daft 与 pyarrow                                        | 基于 Daft 的分析或 ETL       |
| `sql`     | SQLAlchemy（基础依赖中已包含）                                                     | 为自定义技术栈显式固定 SQLAlchemy |
| `full`    | 提供商 (Provider) 与数据库驱动（psycopg2、pgvector、lancedb、elasticsearch、litellm 等） | 使用外部后端的生产工作负载          |

**pip：**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install "heavenbase[full]"
```

**uv：**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv pip install "heavenbase[full]"
```

**poetry：**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poetry add heavenbase --extras "full"
```

**Conda-forge：**

<Note>
  可选 extras 目前是 PyPI 包 extras。Conda-forge 包发布前，请使用 pip、uv 或 Poetry 安装 extras。
</Note>

<br />

## 4. 从源码安装

克隆仓库并用你偏好的方式安装：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
git clone https://github.com/Magolor/HeavenBase.git
cd HeavenBase
```

**pip（可编辑安装，开发推荐）：**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install -e ".[dev]"
```

**从源码安装全部 extras：**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install -e ".[full]"
```

**uv：**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uv pip install -e "."
```

**poetry：**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
poetry install
```

**conda：**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
conda env create -f environment.yml
conda activate hvnb
```

<br />

## 5. 初始化

安装后运行一次 setup。它会创建全局配置存储、初始化 Capsule 注册表并注册默认工作区：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb setup
```

所有包数据位于 `~/.heavenbase/`。更方便的是，随时用 `hb pj %/` 查看路径，其中 `%` 映射到 heavenbase 全局根目录 `~/.heavenbase/`。

<Danger>
  `hb setup --reset` 会销毁所有配置、缓存数据与已注册工作区。此操作不可逆。仅在你打算从头开始时使用。
</Danger>

<br />

## 6. 验证安装

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb --version
# 0.1.1.5
```

快速配置测试：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb llm status -p chat
# preset: chat
# provider: openrouter
# model: deepseek-v4-flash
# model_id: deepseek/deepseek-v4-flash
# gateway: openai
```

status 命令会打印解析后的 LLM preset、provider、model 与 gateway。开箱即用使用 `system` 与 `chat` preset，由 OpenRouter 上的 `deepseek-v4-flash` 支撑——无需改配置文件，只需在环境中设置 `OPENROUTER_API_KEY` 即可。

现在用 HeavenBase README 作为上下文，用默认 LLM 试一次对话：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Setup OPENROUTER_API_KEY in your environment first, then run:
$ hb llm chat "What is HeavenBase?" -i "path:&/README.md"

# HeavenBase is a **metadata-driven data gateway** that lets AI agents interact
# with multiple databases and schema systems through a single, unified interface.
# It doesn't replace your existing stack - it sits on top of it...
```

接下来进入下一章：[First LLM](/zh/quickstart/first-llm) — 快速使用 LLM 进行对话、嵌入、会话与 Python API 调用。

<br />

## 进一步探索

<Tip>
  **下一步：**

  * [首个 LLM](/zh/quickstart/first-llm) — CLI 对话、嵌入、会话与 Python API
  * [LLM provider 集成](/zh/integrations/llm-providers) — 切换到 OpenAI、Anthropic、Ollama 或任意 LiteLLM 兼容 provider
  * [数据库集成](/zh/integrations/databases) — 连接 PostgreSQL、MySQL、DuckDB 等
</Tip>

<br />