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

# 嵌入 (Embeddings)

> HeavenBase 中的文本嵌入生成、批处理与缓存。

<Note>
  *向量应当无聊地可重复——除非你明确想要混乱。*
</Note>

`embed` preset 将文本转为用于搜索、聚类与路由的稠密向量。HeavenBase 以与 chat 相同的方式处理 provider 解析、批处理、去重与缓存——你传入字符串，读回向量。

<br />

## 1. 基本用法 (Basic Usage)

用 `embed` preset 构造 `LLM`（或显式固定 `model=` 与 `provider=`）。`embed` 接受单个字符串或字符串列表：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb

llm = hb.LLM(preset="embed")

vector = llm.embed("hello")
vectors = llm.embed(["hello", "world"])
dim = llm.embed("hello", include="dim")
same_dim = llm.dim
```

默认 `embed` preset 使用可持久化别名 `gpt-embedding-small`，解析为 `text-embedding-3-small`。除非固定 `heavenbase.llm.presets.embed.provider`，否则继承 `heavenbase.llm.default_provider`。

若 chat 默认 provider 不提供嵌入，请单独配置嵌入 preset：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb cfg set heavenbase.llm.presets.embed.provider openai
hb cfg set heavenbase.llm.presets.embed.model text-embedding-3-small
```

已知维度存储在配置中：`embeddinggemma` 为 `768`，`text-embedding-3-small` 为 `1536`，`embed-v4.0` 为 `1536`，`voyage-4-lite` 为 `1024`。`llm.dim` 先读配置；自定义嵌入模型未配置维度时，回退到一次测试嵌入调用。

<br />

## 2. 专用嵌入提供商 (Dedicated Embedding Providers)

Cohere 与 Voyage 是仅嵌入的 provider，没有 OpenRouter 路由。固定 preset provider 并使用捆绑模型键：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb cfg set heavenbase.llm.presets.embed.provider cohere
hb cfg set heavenbase.llm.presets.embed.model embed-v4.0

hb cfg set heavenbase.llm.presets.embed.provider voyage
hb cfg set heavenbase.llm.presets.embed.model voyage-4-lite
```

Provider 后端遵循 LiteLLM 名称（`cohere`、`voyage`）。入口 (Gateway) 专用 `base_url` 位于 `heavenbase.llm.providers`。`gateway="portkey"` 或 `gateway="bifrost"` 时，模型 ID 前缀为 `cohere/embed-v4.0` 与 `voyage/voyage-4-lite`。

<Warning>
  `gateway="portkey"` 搭配 `provider="openrouter"` 的嵌入调用暂时被阻止，因为 Portkey 入口 (Gateway) 尚不支持该路由。在上游支持落地前，OpenRouter 嵌入请使用默认 OpenAI 兼容入口 (Gateway) 或 LiteLLM。
</Warning>

<br />

## 3. Include 投影 (Include Projection)

嵌入响应支持与 chat 相同的 `include` 风格：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
result = llm.embed(
    ["hello", "world"],
    include=["embeddings", "dim", "usage"],
    reduce=False,
)
```

可用字段为 `embeddings`、`usage`、`raw`、`elapsed`、`created_at` 与 `dim`。传 `include=None` 使用默认向量（或向量列表），传字符串选单字段，传列表选多个。

<br />

## 4. CLI 输出 (CLI Output)

`hb llm embed` 默认打印完整原始嵌入数组。`--json` 打印含 `embeddings`、`dim` 与 `usage` 的完整响应对象。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb llm embed "Semantic text"
hb llm embed "Semantic text" --json
```

仅需查看紧凑向量样本时使用 `--preview`。预览模式显示前 4 个与后 2 个值，四舍五入到 6 位小数。`--json --preview` 时输出保持相同对象键，并将 `embeddings` 替换为缩写字符串。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb llm embed "Semantic text" --preview
hb llm embed "Semantic text" --json --preview
```

用 `--copy` / `-cp` 将输出的嵌入结果复制到剪贴板。

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
hb llm embed "Semantic text" --json --copy
```

<br />

## 5. 本地嵌入 (Local Embeddings)

对 LM Studio、Ollama 或其他 OpenAI 兼容本地服务器，使用 `embed-local`：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
local = hb.LLM(preset="embed-local", provider="lmstudio")
vector = local.embed("hello")
```

`embeddinggemma` 在捆绑目录中为仅本地模型，提供 LM Studio 与 Ollama 标识符。

<br />

## 6. 批处理与缓存 (Batching and Cache)

`embed` 在 provider 调用前对重复输入去重，用 `embedding_batch_size` 拆分缓存未命中，以有界的 `embedding_max_workers` 并行处理拆分批次，并将缓存与新鲜向量按原始输入顺序广播回去。

根默认值为 `embedding_batch_size=256` 与 `embedding_max_workers=8`；provider 默认或调用 kwargs 可覆盖。这些控制项不包含在 provider 载荷与缓存键中。

嵌入缓存在 `llm-cache` 工作区下默认启用。用 `hb.LLM(preset="embed", cache=False)` 按实例禁用，或用 `cache=False` 按调用禁用。完整响应缓存模型见 [Advanced LLM](/features/llm/advanced)。

<br />

## Further Exploration

<Tip>
  **Related resources:**

  * [LLM Overview](/features/llm/overview) — preset、模型目录与解析模型。
  * [First LLM](/quickstart/first-llm) — 配置密钥并从 CLI 运行首次 embed。
  * [Advanced LLM](/features/llm/advanced) — 响应缓存、入口 (Gateway) 与上游限制。
</Tip>

<br />