跳到主要内容
版本：1.8.0

向量嵌入

向量嵌入会把文本转换为向量，供应用用于语义搜索、检索流水线、聚类和相似度计算。AISIX AI 网关允许向量嵌入客户端继续使用 OpenAI 兼容的请求和响应格式，同时由网关管理调用方认证、模型别名、上游凭证和策略。

本指南将通过 AISIX 发送一次向量嵌入请求，并说明该端点需要关注的服务提供方行为。

准备工作​

请先准备以下内容：

  • 一个可以处理代理请求的 AISIX 网关。
  • 一个可以访问该模型别名的调用方 API Key。
  • 一个由支持向量嵌入的服务提供方和模型支撑的模型别名。

导出网关连接和请求值：

# AISIX_PROXY 不含尾部斜杠或 /v1 等端点路径
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="text-embedding-prod"

发送向量嵌入请求​

通过网关代理发送向量嵌入请求，并在请求体中使用 AISIX 模型别名：

curl -sS -X POST "${AISIX_PROXY}/v1/embeddings" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "input": [
      "hello",
      "world"
    ]
  }'

AISIX 会解析模型别名、检查调用方 API Key、改写上游模型 ID，并将向量嵌入请求转发给服务提供方。

响应会保持 OpenAI 兼容的向量嵌入格式：

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.0456, 0.0789]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [0.0234, -0.0567, 0.0891]
    }
  ],
  "model": "text-embedding-prod",
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  }
}

向量值可能是浮点数组，也可能是 base64 字符串，具体取决于请求的编码格式和上游响应。

服务提供方与请求行为​

Embeddings 路由接受 OpenAI 兼容的请求形态，并在需要时将其转换为服务提供方的原生 embeddings API：

服务提供方协议族上游 API说明
OpenAI 兼容（适配器 openai）POST {api_base}/embeddings以 OpenAI 形态转发，包括自定义 api_base 部署，并携带 user 以及调用方发送的其他所有字段。
Vertex AI / Gemini（适配器 vertex）google-publisher :predictdimensions 映射为 outputDimensionality；每个输入的 Token 计数会汇总到用量中。
Bedrock（适配器 bedrock）InvokeModelamazon.titan-embed-*（每个输入一次调用；dimensions 在 Text V2 模型上支持，在 Titan Multimodal Embeddings 上以 embeddingConfig.outputEmbeddingLength 发送）和 cohere.embed-*（整批一次调用）。参见 Bedrock 上的 Cohere。
Anthropic不提供 embeddings API请求返回 501。

AISIX 接受单个字符串、字符串数组、token ID 数组（例如 [1, 2]）或 token ID 数组的数组（例如 [[1, 2], [3]]）形式的嵌入输入。转发到上游时会保留调用方的输入形态。调用方无需为单条输入和批量输入编写不同客户端逻辑。

token ID 输入会转发给 OpenAI 兼容上游。Bedrock 和 Vertex AI 的嵌入模型只接受文本，因此 AISIX 会以 400 拒绝发给它们的 token ID 输入。上游没有为 token ID 请求报告用量时，AISIX 会按 token ID 的数量计数。1.7.0 及更早版本的网关在所有上游上都拒绝 token ID 输入。

输入安全护栏可以在 AISIX 调用服务提供方之前检查文本输入。token ID 不包含文本，因此输入安全护栏没有可扫描的内容，会放行 token ID 请求。不要依赖输入安全护栏筛查发送 token ID 的嵌入调用方。

当上游返回 Token 用量时，网关会记录用量。该代理路径下，向量嵌入不会使用 completion Token、响应缓存、流式响应或输出安全护栏。

Bedrock 上的 Cohere​

Bedrock 上的 cohere.embed-* 模型接受三个 Cohere 请求字段，/v1/embeddings 在请求体中接受它们：

字段发送给 Cohere 时
input_typeinput_type，例如 search_query 或 search_document。默认为 search_document。
embedding_typesembedding_types。未设置时由 encoding_format 指定类型；base64 编码基于浮点向量生成。
dimensionsoutput_dimension，仅适用于 Embed v4 模型。更早的模型向量长度固定。

AISIX 能读取 Cohere 的两种响应形状：浮点列表和 Embed v4 的按类型对象；返回多种类型时，返回浮点向量。用量取自 Cohere 的 meta.billed_units.input_tokens（响应中存在时）；否则 Token 数不可用。

排查向量嵌入​

如果 AISIX 返回 501，表示解析出的服务提供方没有 embeddings API（例如 Anthropic）。请使用由上表中某个服务提供方协议族支撑的模型。

对于批量请求，响应应为每个输入项返回一个向量条目。如果返回的向量数量更少，请检查上游响应和网关日志，确认是否存在服务提供方专属的批处理行为。

如果输入安全护栏没有阻断请求，请检查输入是否包含可检查文本。AISIX 可以扫描单个字符串或字符串数组，但不能扫描 token ID。

下一步​

你已经了解 AISIX 如何代理向量嵌入请求，以及服务提供方支持可能存在差异的位置。当应用需要对检索到的文档进行排序时，请继续阅读重排序。