文本嵌入
使用 Embeddings 生成向量，正确选择嵌入模型、解析索引并保持检索一致性。
适用场景
Embeddings 将文本转换成数值向量，常用于语义检索、聚类或相似度排序。接口返回向量而不是自然语言回答，不能用聊天模型的名称或 messages 请求格式替代。
当前代理会查询 GFW 模型目录，并检查模型 ID 中是否包含 embed。模型存在且通过此检查，仍需要有可用的嵌入通道。本文不指定未确认上架的嵌入型号；请从当前 模型库 选择真实模型 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 包。
: "${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"响应字段
以下只展示响应结构，向量数值和用量均为示意，三个维度不代表任何真实模型的输出维度：
{
"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 表示模型不适合当前嵌入路径，不应通过切换成聊天模板绕过。型号不存在会返回模型不可用错误。
检索一致性与相关文档
入库与查询使用同一嵌入模型、维度和预处理方式。切换模型通常需要重新嵌入存量数据；即使向量维度相同，也不代表向量空间兼容。向量库的距离算法、归一化及分块策略应依据模型说明与检索验证结果设置。
不要把所有文档一次提交成无限大批次。按具体模型的输入上限分批，保留输入与向量索引关系，并检查每批结果数量。失败重试会重新发起请求，费用核对见 计费与充值。
相关文档：模型与能力、OpenAI 兼容 API、用量与调用日志、错误码与重试。