# Gemini-Embedding-2 向量嵌入

Gemini-Embedding-2 是 Google 推出的多模态嵌入模型，支持文本、图片、视频、音频和文档等多种内容类型的向量嵌入。

## 什么是 Gemini-Embedding-2

Gemini-Embedding-2 是一个多模态嵌入模型，可以将文本、图片、视频、音频和 PDF 文档转换为高维向量表示。这些嵌入向量可用于：

- **多模态搜索** - 支持跨文本、图片、视频、音频的语义搜索
- **内容推荐** - 基于多模态内容的相似度推荐
- **聚类分析** - 对混合类型的内容进行分组
- **异常检测** - 识别不相关或异常的内容

## 快速开始

### 请求示例

```bash
curl --location --globoff 'https://api.modelverse.cn/v1beta/models/gemini-embedding-2:embedContent' \
--header 'Authorization: Bearer YOUR_MODELVERSE_API_KEY' \
--header 'Content-Type: application/json' \
-d '{
  "content": {
    "parts": [
      {
        "text": "Whats this"
      },
      {
        "text": "Whats this like"
      },
      {
        "file_data": {
          "mime_type": "video/mp4",
          "file_uri": "https://example.com/video.mp4"
        }
      },
      {
        "file_data": {
          "mime_type": "image/png",
          "file_uri": "https://example.com/image.png"
        }
      },
      {
        "file_data": {
          "mime_type": "audio/wav",
          "file_uri": "https://example.com/audio.wav"
        }
      },
      {
        "file_data": {
          "mime_type": "application/pdf",
          "file_uri": "https://example.com/document.pdf"
        }
      }
    ]
  }
}'
```

### 响应示例

```json
{
  "embedding": {
    "values": [
      0.0015015427,
      0.014678672,
      -0.018105509,
      -0.013457718,
      0.015227248,
      0.003112343
    ]
  },
  "usageMetadata": {
    "promptTokenCount": 2517,
    "totalTokenCount": 2517,
    "promptTokensDetails": [
      {
        "modality": "VIDEO",
        "tokenCount": 330
      },
      {
        "modality": "TEXT",
        "tokenCount": 5
      },
      {
        "modality": "DOCUMENT",
        "tokenCount": 1548
      },
      {
        "modality": "IMAGE",
        "tokenCount": 258
      },
      {
        "modality": "AUDIO",
        "tokenCount": 376
      }
    ]
  }
}
```

## API 参考

**POST** `https://api.modelverse.cn/v1beta/models/gemini-embedding-2:embedContent`

### 请求头

| 参数 | 说明 |
|------|------|
| Authorization | Bearer YOUR_MODELVERSE_API_KEY |
| Content-Type | application/json |

### 请求体参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| content | object | 是 | 包含要嵌入的内容 |
| content.parts | array | 是 | 内容部件数组，支持多种模态 |
| outputDimensionality | integer | 否 | 输出嵌入向量的维度，可选值范围 128 至 3072，默认为 3072 |

### 输出维度配置

Gemini-Embedding-2 支持自定义输出维度，可根据场景需求调整：

| 模型 | 默认维度（最高） | 支持的维度（范围） | 建议的较低维度 |
|------|-----------------|-------------------|---------------|
| gemini-embedding-2 | 3072 | 128 至 3072 | 128、768 或 1536 |

**使用建议**：
- 使用较低维度（如 768 或 1536）可减少存储空间和计算成本
- 较低维度可能会略微降低语义搜索的精度，但在大多数场景下差异不明显
- 如需最高精度，请使用默认的 3072 维度

### content.parts 部件类型

#### 文本部件

```json
{
  "text": "要嵌入的文本内容"
}
```

#### 文件部件

```json
{
  "file_data": {
    "mime_type": "video/mp4",
    "file_uri": "https://example.com/video.mp4"
  }
}
```

支持的 MIME 类型：

| 类型 | MIME Type |
|------|-----------|
| 视频 | video/mp4, video/mpeg, video/mov, video/avi 等 |
| 图片 | image/png, image/jpeg, image/webp, image/gif 等 |
| 音频 | audio/wav, audio/mp3, audio/mpeg, audio/ogg 等 |
| 文档 | application/pdf |

### 响应字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| embedding.values | array | 嵌入向量，浮点数列表 |
| usageMetadata.promptTokenCount | integer | 输入内容的总 token 数 |
| usageMetadata.totalTokenCount | integer | 总 token 数 |
| usageMetadata.promptTokensDetails | array | 各模态的 token 使用详情 |
| promptTokensDetails.modality | string | 模态类型：TEXT、IMAGE、VIDEO、AUDIO、DOCUMENT |
| promptTokensDetails.tokenCount | integer | 该模态的 token 数量 |

## 使用场景

### 1. 多模态语义搜索

结合文本、图片、视频等多种内容进行语义搜索：

```bash
curl --location --globoff 'https://api.modelverse.cn/v1beta/models/gemini-embedding-2:embedContent' \
--header 'Authorization: Bearer YOUR_MODELVERSE_API_KEY' \
--header 'Content-Type: application/json' \
-d '{
  "content": {
    "parts": [
      {
        "text": "查找关于机器学习的视频教程"
      },
      {
        "file_data": {
          "mime_type": "image/png",
          "file_uri": "https://example.com/ml-diagram.png"
        }
      }
    ]
  }
}'
```

### 2. 视频内容分析

提取视频内容的嵌入向量用于分类或推荐：

```bash
curl --location --globoff 'https://api.modelverse.cn/v1beta/models/gemini-embedding-2:embedContent' \
--header 'Authorization: Bearer YOUR_MODELVERSE_API_KEY' \
--header 'Content-Type: application/json' \
-d '{
  "content": {
    "parts": [
      {
        "file_data": {
          "mime_type": "video/mp4",
          "file_uri": "https://example.com/tutorial.mp4"
        }
      }
    ]
  }
}'
```

### 3. 文档理解

将 PDF 文档转换为嵌入向量：

```bash
curl --location --globoff 'https://api.modelverse.cn/v1beta/models/gemini-embedding-2:embedContent' \
--header 'Authorization: Bearer YOUR_MODELVERSE_API_KEY' \
--header 'Content-Type: application/json' \
-d '{
  "content": {
    "parts": [
      {
        "text": "总结这份报告的关键点"
      },
      {
        "file_data": {
          "mime_type": "application/pdf",
          "file_uri": "https://example.com/report.pdf"
        }
      }
    ]
  }
}'
```

### 4. 音频内容嵌入

处理音频文件获取其语义表示：

```bash
curl --location --globoff 'https://api.modelverse.cn/v1beta/models/gemini-embedding-2:embedContent' \
--header 'Authorization: Bearer YOUR_MODELVERSE_API_KEY' \
--header 'Content-Type: application/json' \
-d '{
  "content": {
    "parts": [
      {
        "file_data": {
          "mime_type": "audio/wav",
          "file_uri": "https://example.com/speech.wav"
        }
      }
    ]
  }
}'
```

### 5. 指定输出维度

使用 `outputDimensionality` 参数指定输出向量的维度（如 768）：

```bash
curl --location --globoff 'https://api.modelverse.cn/v1beta/models/gemini-embedding-2:embedContent' \
--header 'Authorization: Bearer YOUR_MODELVERSE_API_KEY' \
--header 'Content-Type: application/json' \
-d '{
  "outputDimensionality": 768,
  "content": {
    "parts": [
      {
        "text": "Whats this"
      },
      {
        "file_data": {
          "mime_type": "video/mp4",
          "file_uri": "gs://cloud-samples-data/generative-ai/video/pixel8.mp4"
        }
      }
    ]
  }
}'
```

## 技术规范

### 图片

| 限制项 | 规格 |
| --- | --- |
| 每个提示的图片数量上限 | 6 |
| 内嵌数据或通过控制台直接上传的每个文件的文件大小上限 | 无限制 |
| Google Cloud Storage 中每个文件的文件大小上限 | 无限制 |
| 每个提示的输出图片数量上限 | 不适用 |
| 支持的 MIME 类型 | `image/png`、`image/jpeg`、`image/webp`、`image/bmp`、`image/heic`、`image/heif`、`image/avif` |

### 文档

| 限制项 | 规格 |
| --- | --- |
| 每个提示的文件数量上限 | 1 |
| 每个文件的页数上限 | 6 |
| 每个文件的文件大小上限 | 不适用 |
| 支持的 MIME 类型 | `application/pdf` |

### 视频

| 限制项 | 规格 |
| --- | --- |
| 视频时长上限（包含音频） | 80 秒 |
| 视频时长上限（不含音频） | 120 秒 |
| 每个提示的视频数量上限 | 1 |
| 支持的 MIME 类型 | `video/mpeg`、`video/mp4` |

### 音频

| 限制项 | 规格 |
| --- | --- |
| 每个提示的音频长度上限 | 180 秒 |
| 每个提示的音频文件数量上限 | 1 |
| 支持的 MIME 类型 | `audio/mp3`、`audio/wav` |

## 注意事项

1. **文件 URI**：文件需要通过可公开访问的 URL 提供，或者使用 Gemini 的文件上传 API 获取 URI
2. **文件大小限制**：不同模态的文件有不同的大小限制，请参考上方技术规范
3. **Token 计算**：多模态内容的 token 计算方式不同，具体使用量请参考响应中的 `usageMetadata`
4. **嵌入维度**：Gemini-Embedding-2 支持通过 `outputDimensionality` 参数自定义输出维度（128 至 3072），默认为 3072。使用较低维度可减少存储成本，具体请参考上方"输出维度配置"章节

## 与标准 Embeddings API 的区别

| 特性 | Gemini-Embedding-2 | 标准 Embeddings API |
|------|-------------------|---------------------|
| 支持的模态 | 文本、图片、视频、音频、PDF | 仅文本 |
| API 端点 | `/v1beta/models/gemini-embedding-2:embedContent` | `/v1/embeddings` |
| 请求格式 | Gemini 原生格式 | OpenAI 兼容格式 |
| 多模态混合 | 支持单请求多模态 | 不支持 |

## 相关文档

- [Embeddings 向量嵌入](./embeddings.md) - 标准文本嵌入 API
- [Gemini 快速开始](./gemini_compatible.md) - Gemini 模型使用指南
- [Gemini 媒体分析](./gemini-media-analysis.md) - 媒体文件处理说明