跳到主要内容

向量嵌入

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

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

准备工作​

请先准备以下内容：

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

发送向量嵌入请求​

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

curl -sS -X POST "http://127.0.0.1:3000/v1/embeddings" \
  -H "Authorization: Bearer YOUR_CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-prod",
    "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-3-small",
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  }
}

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

服务提供方与请求行为​

Embeddings 路由是 OpenAI 兼容代理路径。服务提供方支持情况取决于解析出的适配器和你配置的模型。

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

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

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

向量嵌入行为​

如果 AISIX 返回 501，表示解析出的服务提供方适配器不支持向量嵌入。请求不会被转换为另一种服务提供方格式；请使用由支持向量嵌入的服务提供方支撑的模型。

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

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

下一步​

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