跳转到主要内容
Embeddings 把文本转换为向量,适用于语义检索、聚类等场景。生成向量接口只返回向量,不会自动建立索引或保存文档。模型列表中的模型不一定支持向量接口,请先确认部署中的可用模型。

Python:批量向量与小规模检索

按 Python SDK设置 API_BASE_URL(包含 /v1)、API_KEY、向量模型的 API_MODEL。保存为 embeddings.py,执行 python embeddings.py。示例将一个查询与两段候选文本一起发送,按响应 index 恢复对应关系,归一化后计算余弦相似度,再输出排序后的原文。 这只是内存中的小规模演示,适用于允许查询和文档使用相同编码方式的模型。需要 query/document 前缀或任务类型的模型,应按照模型要求分别编码;不要直接套用本例。真实排名由模型决定,不承诺某段文本一定排第一。

输入、编码和维度

  • 本指南使用单个字符串或字符串数组。上游 OpenAI 还接受 token ID 数组,但网关的文本提取与部分渠道转换只处理字符串,不能把 token 数组视为跨渠道通用输入。
  • 示例显式传 encoding_format: float,并校验非空、有限数值、非零向量、统一维度和完整且不重复的索引。data 的数组位置不能代替 index。
  • dimensions 只在模型和渠道支持时设置;不要随意截断向量。Base64 返回也是能力相关选项,例如当前 Jina 适配器会去掉 encoding_format,因此必须检查实际返回类型。
  • 文本长度、单批条数和总 token 限制由部署与模型决定。不要把字符数当 token 数;先切分长文档,再按限制分批。两个接口都是同步 JSON,不提供本页所述请求的 SSE 输出。

从演示到检索应用

文档向量通常离线生成并保存,查询时只编码查询。记录文档 ID、分块 ID、模型版本、维度和预处理方式;查询与文档必须处于兼容的向量空间。相同维度不代表不同模型的向量可以混用,更换模型或编码方式通常需要重新建索引。确认模型是否已归一化及索引使用的距离度量,本例自行归一化来计算余弦。 由应用或向量数据库完成候选召回,再把候选文本交给 Rerank精排。召回与精排前均应限制到当前用户可访问的文档,不能依赖模型过滤权限;Rerank 看不到没有传入的文档。真实向量数据库接入不包含在此演示中。

故障处理

400 时核对输入类型、长度、维度和编码选项;401/403 检查密钥与模型访问;429 按错误处理退避。HTTP 200 但少向量、重复索引或维度不一致时,拒绝写入索引,记录请求标识后排查。示例关闭自动重试,不打印密钥或完整错误响应。 字段含义参考 OpenAI Embeddings API;跨渠道行为以本项目适配器及实际部署为准。 下一步:用 RAG 知识库问答将召回、可选重排与带来源回答串成完整流程。 Read in English