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

# 向量嵌入

> 使用 Gemini 的 Embeddings 接口生成文本语义向量。

`POST /gemini/v1beta/models/{model}:embedContent` 用于生成文本的向量表示，适用于语义搜索、文本分类、聚类等场景。

## 基础请求

```bash theme={null}
curl -X POST "$BASE_URL/gemini/v1beta/models/text-embedding-004:embedContent" \
  -H "x-goog-api-key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "parts": [{"text": "Rivus AI 是一个多云模型网关。"}]
    }
  }'
```

## 响应示例

```json theme={null}
{
  "embedding": {
    "values": [0.123, -0.456, 0.789, ...]
  }
}
```

## 批量嵌入

如需处理多个文本，可以使用 `requests` 数组：

```bash theme={null}
curl -X POST "$BASE_URL/gemini/v1beta/models/text-embedding-004:batchEmbedContents" \
  -H "x-goog-api-key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {"content": {"parts": [{"text": "第一段文本"}]}},
      {"content": {"parts": [{"text": "第二段文本"}]}},
      {"content": {"parts": [{"text": "第三段文本"}]}}
    ]
  }'
```

## 任务类型

通过 `taskType` 参数指定嵌入用途，可以优化向量质量：

```json theme={null}
{
  "content": {
    "parts": [{"text": "搜索查询文本"}]
  },
  "taskType": "RETRIEVAL_QUERY"
}
```

支持的任务类型：

* `RETRIEVAL_QUERY`：检索查询（用户搜索词）
* `RETRIEVAL_DOCUMENT`：检索文档（被搜索的文档）
* `SEMANTIC_SIMILARITY`：语义相似度计算
* `CLASSIFICATION`：文本分类
* `CLUSTERING`：文本聚类

## 输出维度

部分模型支持自定义输出维度：

```json theme={null}
{
  "content": {
    "parts": [{"text": "文本内容"}]
  },
  "outputDimensionality": 256
}
```

<Callout type="info">
  `text-embedding-004` 默认输出 768 维向量，支持降维到 256 维以节省存储空间。
</Callout>

## OpenAI 兼容方式

也可以使用 OpenAI 风格的 Embeddings 接口：

```bash theme={null}
curl -X POST "$BASE_URL/v1/embeddings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-004",
    "input": "Rivus AI 是一个多云模型网关。"
  }'
```

Rivus AI 会自动完成格式转换，返回标准 OpenAI 格式的响应。

## 常见用途

* **语义搜索**：将文档和查询转换为向量，通过余弦相似度找到最相关的文档
* **文本分类**：使用向量作为特征输入到分类模型
* **去重与聚类**：通过向量相似度识别重复或相似内容
* **推荐系统**：基于内容向量计算相似度进行推荐

<Callout type="tip">
  建议为查询和文档使用不同的 `taskType`，可以显著提升检索效果。
</Callout>