帮你快速理解、总结文档立即下载
文档中心>Elasticsearch Service>智能搜索开发指南>原子服务>OpenAI API 调用原子服务

OpenAI API 调用原子服务

最近更新时间：2026-08-10 15:22:02
我的收藏

本页目录：

本文介绍如何通过 OpenAI 兼容协议调用智能搜索开发的原子模型服务。原子服务的接口设计兼容 OpenAI API 风格，可直接使用 OpenAI 官方 SDK 或任意 HTTP 客户端接入，无需依赖 Elasticsearch 实例。每个模型服务都有默认限频，如有更多需求，请 联系我们。

概述

支持通过 OpenAI 协议调用的服务如下，具体模型详情请参见：原子服务概览
服务
接口路径
说明
文本向量化
POST /v1/embeddings
将文本转换为稠密向量
重排序
POST /v1/rerank
对候选文档按相关性重新排序
多模态向量化
POST /v1/multimodal-embeddings
将文本和图片映射到统一向量空间
适用场景：
业务代码需要独立调用向量化、重排序能力，不经过 Elasticsearch。
已有基于 OpenAI SDK 的代码，希望以最小改动切换到腾讯云原子服务。
需要使用多模态向量化能力。

前提条件

已开通原子服务。
已获取 API Key。API Key 可在 腾讯云 ES 控制台 的 资源管理 > API Key 页面创建和管理。

通用说明

服务地址

项目
说明
Base URL
https://bj.aisearch.tencentelasticsearch.com
协议
HTTP/HTTPS
Content-Type
application/json
字符编码
UTF-8
超时时间
默认 60 秒

认证方式

所有接口均需在请求头中携带 Bearer Token：
Authorization: Bearer sk-<your-api-key>

错误响应格式

所有错误响应遵循统一格式：
{
  "error": {
    "message": "错误描述信息",
    "type": "错误类型",
    "code": "错误码"
  }
}

错误码列表

HTTP 状态码
code
type
说明
401
missing_api_key
invalid_request_error
缺少 Authorization 请求头
401
invalid_api_key
invalid_request_error
Token 无效或签名校验失败
403
account_disabled
invalid_request_error
账号已被禁用
403
ip_blocked
invalid_request_error
IP 地址被黑名单拦截
403
ip_not_allowed
invalid_request_error
IP 地址不在白名单中
403
UnsupportedOperation
permission_error
原子服务未开通
429
LimitExceeded
rate_limit_error
免费额度用完
429
RequestLimitExceeded
rate_limit_error
后端限流触发
429
rate_limit_exceeded
invalid_request_error
请求频率超限

限流响应头

每个成功的请求响应中会包含以下限流信息头（OpenAI 兼容）：
响应头
说明
示例
X-RateLimit-Limit-Requests
令牌桶容量（最大突发请求数）
20
X-RateLimit-Remaining-Requests
当前剩余可用令牌数
19
X-RateLimit-Reset-Requests
令牌恢复时间
50ms 或 1.0s

文本向量化 - POST /v1/embeddings

将文本转换为向量表示。兼容 OpenAI Embeddings API 格式。

支持的模型

模型名称：
bge-base-zh-v1.5
bge-large-zh-v1.5
bge-m3
Conan-embedding-v1
KaLM-embedding-multilingual-mini-v1
Qwen3-Embedding-0.6B

请求参数

参数
类型
必填
说明
model
string
是
模型名称
input
string | string[]
是
输入文本，支持单条字符串或字符串数组（批量）

请求示例

单次请求：
cURL
curl -s https://bj.aisearch.tencentelasticsearch.com/v1/embeddings \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer sk-****" \\
  -d '{
    "model": "bge-m3",
    "input": "你好，这是一个测试"
  }' | jq .
批量请求：
cURL
curl -s https://bj.aisearch.tencentelasticsearch.com/v1/embeddings \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer sk-****" \\
  -d '{
    "model": "bge-m3",
    "input": ["人工智能正在改变世界", "深度学习是机器学习的一个子领域"]
  }' | jq .

响应示例

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0123, -0.0456, ...]
    }
  ],
  "model": "bge-m3",
  "usage": {
    "prompt_tokens": 12,
    "total_tokens": 12
  }
}
说明：
批量请求时，响应 data 数组中的元素顺序与请求 input 数组一致，也可通过 index 字段对应。

重排序 - POST /v1/rerank

对候选文档相对于查询的相关性进行重新排序，通常用于检索结果的重排环节。

支持的模型

模型名称：
bge-reranker-large
bge-reranker-v2-m3

请求参数

参数
类型
必填
说明
model
string
是
模型名称
query
string
是
查询文本
documents
string[]
是
候选文档列表
top_n
number
否
返回前 N 个结果，默认返回全部
return_documents
boolean
否
是否在结果中返回文档内容，默认 false

请求示例

cURL
curl -s https://bj.aisearch.tencentelasticsearch.com/v1/rerank \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer sk-****" \\
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "What is artificial intelligence",
    "documents": ["Artificial intelligence is a branch of computer science", "The weather is nice today", "Machine learning is the core technology of AI"],
    "top_n": 3,
    "return_documents": true
  }' | jq .

响应示例

{
	"object": "rerank",
	"results": [{
		"index": 0,
		"relevance_score": 0.9992678761482239,
		"document": {
			"text": "Artificial intelligence is a branch of computer science"
		}
	}, {
		"index": 2,
		"relevance_score": 0.939024806022644,
		"document": {
			"text": "Machine learning is the core technology of AI"
		}
	}, {
		"index": 1,
		"relevance_score": 0.00007484622619813308,
		"document": {
			"text": "The weather is nice today"
		}
	}],
	"model": "bge-reranker-large",
	"usage": {
		"total_tokens": 218
	}
}

说明：
results 数组按 relevance_score 降序排列，index 字段对应请求中 documents 数组的原始下标。若 return_documents 为 false（默认值），响应中不包含 document 字段，需通过 index 自行映射回原文档。

多模态向量化 - POST /v1/multimodal-embeddings

将文本和图片转换为统一向量空间中的向量表示，适用于以文搜图、以图搜图等跨模态检索场景。

支持的模型

模型名称：
WeCLIPv2-Base
WeCLIPv2-Large

请求参数

参数
类型
必填
说明
model
string
是
模型名称
texts
string[]
否*
文本数组
image_url
string[]
否*
图片 URL 数组
image_data
string[]
否*
base64 图片数组，格式：data:<MIME>;base64,<内容>
说明：
该接口使用自定义格式，不兼容 OpenAI 标准的 input 数组格式，必须使用顶层字段 texts、image_url、image_data 三者至少传一个。image_data 和 image_url 不能同时传。

请求示例

纯文本模式：
cURL
curl -s https://bj.aisearch.tencentelasticsearch.com/v1/multimodal-embeddings \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer sk-****" \\
  -d '{
    "model": "WeCLIPv2-Large",
    "texts": ["一只可爱的猫咪", "美丽的风景照"]
  }' | jq .
文本 + 图片 URL 混合模式：
cURL
curl -s https://bj.aisearch.tencentelasticsearch.com/v1/multimodal-embeddings \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer sk-****" \\
  -d '{
    "model": "WeCLIPv2-Large",
    "texts": ["这是一段文本"],
    "image_url": ["https://example.com/image.png"]
  }' | jq .
文本 + 图片 base64 混合模式：
cURL
curl -s https://bj.aisearch.tencentelasticsearch.com/v1/multimodal-embeddings \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer sk-****" \\
  -d '{
    "model": "WeCLIPv2-Base",
    "texts": ["一只猫"],
    "image_data": [
      "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
    ]
  }' | jq .

响应示例

{
  "object": "multimodal_embedding",
  "data": {
    "text_embeddings": [
      {
        "object": "embedding",
        "index": 0,
        "embedding": [0.0123, -0.0456, ...]
      }
    ],
    "image_embeddings": [
      {
        "object": "embedding",
        "index": 0,
        "embedding": [0.0789, -0.0321, ...]
      }
    ]
  },
  "model": "WeCLIPv2-Large",
  "usage": {
    "total_tokens": 5,
    "total_images": 1
  }
}
与文本向量化接口不同，多模态接口的向量位于 data.text_embeddings 和 data.image_embeddings 两个数组中，而非顶层 data 数组。
文本向量与图片向量位于同一向量空间，可直接计算余弦相似度实现跨模态检索。实际生产场景中，图片向量通常预先计算并写入 Elasticsearch 的 dense_vector 字段，检索时只需实时计算查询文本的向量，再通过 kNN 检索完成匹配。

接口速查表

接口路径
方法
支持的模型
响应格式
说明
/v1/embeddings
POST
bge-base-zh-v1.5、bge-large-zh-v1.5、bge-m3、Conan-embedding-v1、KaLM-embedding-multilingual-mini-v1、Qwen3-Embedding-0.6B
JSON
文本向量化
/v1/rerank
POST
bge-reranker-large、bge-reranker-v2-m3
JSON
重排序
/v1/multimodal-embeddings
POST
WeCLIPv2-Base、WeCLIPv2-Large
JSON
多模态向量化

注意事项

API Key 安全：不要将 API Key 硬编码在前端代码或提交到代码仓库。建议由后端服务代理调用，或通过环境变量、密钥管理服务注入。
限流处理：向量化和重排序模型默认限流为 20 QPS。触发限流时接口返回 429，建议在客户端实现指数退避重试，并结合响应头中的 X-RateLimit-Reset-Requests 控制重试间隔。
批量优先：文本向量化接口支持数组批量输入，同一批文本合并为一次请求可显著降低请求次数，避免触发限流。
多模态接口响应结构特殊：多模态向量化的响应结构与其他接口不同，向量嵌套在 data.text_embeddings 和 data.image_embeddings 中，解析时请注意区分。
计费：调用原子服务会产生原子模型服务费用，按实际 Token 量计费。计费详情请参见 智能搜索开发定价。

相关文档

ES Inference API 调用：通过 Elasticsearch Inference API 调用文本向量化、重排序、LLM 对话，以及查询分析、文档解析、文本切片服务。
资源管理 > API Key：API Key 的创建与管理。

中国站