# 文本嵌入

使用 Embeddings 生成向量，正确选择嵌入模型、解析索引并保持检索一致性。

## 适用场景 [#适用场景]

Embeddings 将文本转换成数值向量，常用于语义检索、聚类或相似度排序。接口返回向量而不是自然语言回答，不能用聊天模型的名称或 `messages` 请求格式替代。

当前代理会查询 GFW 模型目录，并检查模型 ID 中是否包含 `embed`。模型存在且通过此检查，仍需要有可用的嵌入通道。本文不指定未确认上架的嵌入型号；请从当前 [模型库](/models) 选择真实模型 ID，设置为 `GFW_EMBEDDING_MODEL`。

## 端点与鉴权 [#端点与鉴权]

| 项目 | 值 |
| --- | --- |
| 端点 | `POST https://api.gfw.net/v1/embeddings` |
| OpenAI SDK `base_url` | `https://api.gfw.net/v1` |
| 鉴权 | `Authorization: Bearer $GFW_API_KEY` |
| 请求格式 | JSON，不使用聊天消息模板 |

该处理器转发嵌入请求及上游响应，不把内容转换成 Chat Completions。协议兼容不意味着自动创建向量数据库、检索索引或知识库；这些工作仍由应用负责。

## 请求参数 [#请求参数]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 当前可用的 GFW 嵌入模型 ID，不能使用厂商路径前缀 |
| `input` | string / array of strings | 业务请求是 | 一段文本或文本列表；具体批量大小与长度限制由模型决定 |
| `encoding_format` | string | 否 | 示例请求 `float`；是否支持 `base64` 等其他格式需模型确认 |
| `dimensions` | integer | 否 | 缩减向量维度的条件参数，不是所有嵌入模型支持，首次接入建议省略 |
| 其他扩展字段 | 依模型而定 | 否 | 原始 JSON 可被转发，不能据此承诺上游支持 |

处理器只在入口显式提取 `model` 和 `input`；不要把“入口未严格拒绝某种 input”理解为此种输入一定有效。Token ID 数组、额外编码与批量限制均需具体模型契约确认，本文仅使用文本输入。

## 完整调用示例 [#完整调用示例]

提前设置 `GFW_API_KEY` 和 `GFW_EMBEDDING_MODEL`。cURL 示例使用本地 Python 生成 JSON，避免环境变量插入破坏 JSON 语法；不会在本地生成向量。Python SDK 示例依赖 `openai` 包。



**cURL**


```bash
: "${GFW_API_KEY:?请先设置 GFW_API_KEY}"
: "${GFW_EMBEDDING_MODEL:?请设置模型库中真实可用的嵌入模型 ID}"

payload=$(python -c 'import json, os; print(json.dumps({"model": os.environ["GFW_EMBEDDING_MODEL"], "input": ["连接池复用数据库连接。", "请求超时限制等待时间。"], "encoding_format": "float"}, ensure_ascii=False))')

curl --fail-with-body --silent --show-error \
  --max-time 120 \
  https://api.gfw.net/v1/embeddings \
  -H "Authorization: Bearer ${GFW_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data "$payload"
```



**Python**


```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GFW_API_KEY"],
    base_url="https://api.gfw.net/v1",
    timeout=120.0,
    max_retries=0,
)
texts = ["连接池复用数据库连接。", "请求超时限制等待时间。"]
response = client.embeddings.create(
    model=os.environ["GFW_EMBEDDING_MODEL"],
    input=texts,
    encoding_format="float",
)

items = sorted(response.data, key=lambda item: item.index)
if [item.index for item in items] != list(range(len(texts))):
    raise RuntimeError("响应索引与输入数量不匹配")
dimensions = {len(item.embedding) for item in items}
if len(dimensions) != 1 or 0 in dimensions:
    raise RuntimeError("向量维度为空或不一致")
for item in items:
    print("index:", item.index, "dimensions:", len(item.embedding))
print("usage:", response.usage)
```




## 响应字段 [#响应字段]

以下只展示响应结构，向量数值和用量均为示意，三个维度不代表任何真实模型的输出维度：

```json
{
  "object": "list",
  "data": [{"object": "embedding", "index": 0, "embedding": [0.12, -0.04, 0.31]}],
  "usage": {"prompt_tokens": 12, "total_tokens": 12}
}
```

| 字段 | 处理方式 |
| --- | --- |
| `data[].index` | 对应输入位置，按索引匹配文本，不仅依赖数组顺序 |
| `data[].embedding` | 浮点向量，维度由模型及请求参数决定 |
| `model` | 响应中的模型标识；应用另存请求时使用的 GFW 模型 ID |
| `usage` | 用量字段，不能直接解释成 元金额 |

错误如 `embedding_not_supported` 表示模型不适合当前嵌入路径，不应通过切换成聊天模板绕过。型号不存在会返回模型不可用错误。

## 检索一致性与相关文档 [#检索一致性与相关文档]

入库与查询使用同一嵌入模型、维度和预处理方式。切换模型通常需要重新嵌入存量数据；即使向量维度相同，也不代表向量空间兼容。向量库的距离算法、归一化及分块策略应依据模型说明与检索验证结果设置。

不要把所有文档一次提交成无限大批次。按具体模型的输入上限分批，保留输入与向量索引关系，并检查每批结果数量。失败重试会重新发起请求，费用核对见 [计费与充值](/docs/billing)。

相关文档：[模型与能力](/docs/models)、[OpenAI 兼容 API](/docs/openai-api)、[用量与调用日志](/docs/usage-logs)、[错误码与重试](/docs/errors)。