跳到主要内容

向量嵌入

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

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

准备工作​

请先准备以下内容：

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

导出网关连接和请求值：

# AISIX_PROXY 末尾不含斜杠，也不包含 /v1 等端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
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 部署。
Vertex AI / Gemini（适配器 vertex）google-publisher :predictdimensions 映射为 outputDimensionality；每个输入的 Token 计数会汇总到用量中。
Bedrock（适配器 bedrock）InvokeModelamazon.titan-embed-*（每个输入一次调用；dimensions 仅在 V2 模型上支持）和 cohere.embed-*（整批一次调用）。
Anthropic不提供 embeddings API请求返回 501。

AISIX 接受单个字符串或字符串数组形式的嵌入输入。转发到上游时会保留调用方的输入形态。调用方无需为单条输入和批量输入编写不同客户端逻辑。

输入安全护栏可以在 AISIX 调用服务提供方之前检查这些受支持输入形式中的文本。当前该网关路由不支持 Token 数组输入。

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

排查向量嵌入​

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

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

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

下一步​

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