概述
向量模型可以将文本、图片等输入内容转换为向量表示,适用于语义检索、相似度计算、文本聚类、文本分类和图文检索等场景。
TokenHub 支持通过 API 调用向量模型。本次上线的向量模型包括文本向量模型和多模态向量模型。
前提条件
已注册腾讯云账号并开通 TokenHub 服务。
已在 TokenHub 控制台 获取 API Key。
已根据所用语言安装对应 SDK 或具备 HTTP 请求能力。
支持的模型
模型类型 | model 参数值 | 输出维度 | 上下文长度 | 推荐场景 |
文本向量模型 | kinfra-text-embedding-0.6b | 1024 | 32k | 大规模文本召回、延迟敏感、成本敏感场景 |
文本向量模型 | kinfra-text-embedding-4b | 2560 | 32k | 高质量文本检索、深层语义理解场景 |
多模态向量模型 | kinfra-vl-embedding-2b | 2048 | 32k | 多模态在线检索、视频检索、响应速度优先场景 |
多模态向量模型 | kinfra-vl-embedding-8b | 4096 | 32k | 高精度多模态检索、精度优先场景 |
说明:
以上模型均支持 30 余种主流语言,包括中文、英语、日语、韩语、法语、德语、俄语、葡萄牙语、西班牙语等。
文本向量
文本向量接口用于将文本转换为向量表示。接口兼容 OpenAI Embeddings API 的请求和响应结构。
接口地址
POST https://tokenhub.tencentmaas.com/v1/embeddings
请求参数
参数 | 类型 | 必填 | 说明 |
model | String | 是 | 服务 ID。可在在线推理服务页面查看。平台默认服务的服务 ID 与模型名称相同;自定义服务的服务 ID 格式为 ep-xxxxxxxx。 |
input | String 或 Array | 是 | 输入文本。支持传入单条文本或文本数组。单条文本不超过 2000 字符。单次请求建议不超过 128 条文本。 |
encoding_format | String | 否 | 向量编码格式。仅支持 float,默认值为 float。 |
dimensions | Integer | 否 | 输出向量维度由模型决定,不支持自定义。 kinfra-text-embedding-0.6b 固定输出 1024 维,kinfra-text-embedding-4b 固定输出 2560 维。 |
请求示例
curl -X POST 'https://tokenhub.tencentmaas.com/v1/embeddings' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-H 'Content-Type: application/json' \\-d '{"model": "kinfra-text-embedding-0.6b","input": "腾讯云 TokenHub 是一站式 AI 大模型服务平台。","encoding_format": "float"}'
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1")response = client.embeddings.create(model="kinfra-text-embedding-0.6b",input="腾讯云 TokenHub 是一站式 AI 大模型服务平台。",encoding_format="float")print(response.data[0].embedding)
import OpenAI from 'openai';const client = new OpenAI({apiKey: 'YOUR_API_KEY',baseURL: 'https://tokenhub.tencentmaas.com/v1'});async function main() {const response = await client.embeddings.create({model: 'kinfra-text-embedding-0.6b',input: '腾讯云 TokenHub 是一站式 AI 大模型服务平台。',encoding_format: 'float'});console.log(response.data[0].embedding);}main();
package mainimport ("bytes""encoding/json""fmt""io""net/http")func main() {body, err := json.Marshal(map[string]interface{}{"model": "kinfra-text-embedding-0.6b","input": "腾讯云 TokenHub 是一站式 AI 大模型服务平台。","encoding_format": "float",})if err != nil {panic(err)}req, err := http.NewRequest("POST","https://tokenhub.tencentmaas.com/v1/embeddings",bytes.NewBuffer(body))if err != nil {panic(err)}req.Header.Set("Authorization", "Bearer YOUR_API_KEY")req.Header.Set("Content-Type", "application/json")resp, err := http.DefaultClient.Do(req)if err != nil {panic(err)}defer resp.Body.Close()data, err := io.ReadAll(resp.Body)if err != nil {panic(err)}fmt.Println(string(data))}
import okhttp3.*;import com.google.gson.Gson;import java.util.*;public class TextEmbeddingQuickStart {public static void main(String[] args) throws Exception {Map<String, Object> body = new HashMap<>();body.put("model", "kinfra-text-embedding-0.6b");body.put("input", "腾讯云 TokenHub 是一站式 AI 大模型服务平台。");body.put("encoding_format", "float");Request request = new Request.Builder().url("https://tokenhub.tencentmaas.com/v1/embeddings").header("Authorization", "Bearer YOUR_API_KEY").header("Content-Type", "application/json").post(RequestBody.create(new Gson().toJson(body), MediaType.parse("application/json"))).build();try (Response response = new OkHttpClient().newCall(request).execute()) {System.out.println(response.body().string());}}}
批量输入示例
以下示例展示如何传入多条文本进行批量向量化:
curl -X POST 'https://tokenhub.tencentmaas.com/v1/embeddings' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-H 'Content-Type: application/json' \\-d '{"model": "kinfra-text-embedding-0.6b","input": ["什么是 RAG?", "向量模型用于语义检索", "TokenHub 是一站式 AI 大模型服务平台"]}'
response = client.embeddings.create(model="kinfra-text-embedding-0.6b",input=["什么是 RAG?", "向量模型用于语义检索", "TokenHub 是一站式 AI 大模型服务平台"])for item in response.data:print(f"index={item.index}, dim={len(item.embedding)}")
响应示例
以下示例仅展示响应结构,向量值和 token 数以实际返回为准。
{"object": "list","data": [{"object": "embedding","index": 0,"embedding": [0.0123, -0.0456, 0.0789]}],"model": "kinfra-text-embedding-0.6b","usage": {"prompt_tokens": 10,"total_tokens": 10,"prompt_tokens_details": {"text_tokens": 10,"image_tokens": 0,"video_tokens": 0}}}
响应参数
基础字段:
参数 | 类型 | 说明 |
object | String | 固定为 list |
model | String | 本次请求使用的模型 ID |
data | Array | 向量结果列表 |
data[].object | String | 固定为 embedding |
data[].index | Integer | 输入内容在请求数组中的序号 |
data[].embedding | Array | 向量数组,浮点数格式 |
usage 字段:
参数 | 类型 | 说明 |
usage.prompt_tokens | Integer | 输入内容消耗的 token 总数 |
usage.total_tokens | Integer | 本次请求消耗的 token 总数 |
usage.prompt_tokens_details | Object | 输入 token 明细(多模态场景下按模态细分) |
usage.prompt_tokens_details.text_tokens | Integer | 文本输入消耗的 token 数 |
usage.prompt_tokens_details.image_tokens | Integer | 图片输入消耗的 token 数 |
usage.prompt_tokens_details.video_tokens | Integer | 视频输入消耗的 token 数 |
多模态向量
多模态向量接口用于将文本、图片和视频转换为向量表示。接口支持在单次请求中同时传入文本、图片和视频,适用于图文检索和多模态语义检索场景。
接口地址
POST https://tokenhub.tencentmaas.com/v1/embeddings/multimodal
请求参数
参数 | 类型 | 必填 | 说明 |
model | String | 是 | 服务 ID。可在在线推理服务页面查看。平台默认服务的服务 ID 与模型名称相同;自定义服务的服务 ID 格式为 ep-xxxxxxxx。 |
input | Array | 是 | 多模态输入列表,元素类型支持 text、image_url 和 video_url。 |
input[].type | String | 是 | 输入类型。取值: text、image_url、video_url。 |
input[].text | String | 否 | 文本内容。当 type 为 text 时填写。 |
input[].image_url | Object | 否 | 图片地址对象。当 type 为 image_url 时填写。 |
input[].image_url.url | String | 否 | 图片 URL 或 base64 内容。 |
input[].video_url | Object | 否 | 视频地址对象。当 type 为 video_url 时填写。 |
input[].video_url.url | String | 否 | 视频 URL 或 base64 内容。 |
instructions | String | 否 | 推理提示词。不传入时,系统按输入模态生成默认值。 |
encoding_format | String | 否 | 向量编码格式。仅支持 float,默认值为 float。 |
dimensions | Integer | 否 | 输出向量维度由模型决定,不支持自定义。 kinfra-vl-embedding-2b 固定输出 2048 维,kinfra-vl-embedding-8b 固定输出 4096 维。 |
使用限制
限制项 | 说明 |
多模态输入类型 | 仅支持 text、image_url、video_url 三种类型 |
图片格式 | 支持 JPEG、PNG、WEBP、BMP、TIFF 等格式 |
图片最小像素 | 4,096(约 64 x 64) |
图片最大像素 | 1,843,200(约 1280 x 1440) |
视频格式 | 支持 MP4、AVI、MOV |
视频总像素上限 | 7,864,320 |
视频最大采样帧数 | 64 |
视频 fps | 默认 1.0 |
多模态序列长度 | 最大序列长度为 32,768 tokens |
向量归一化 | 默认 L2 归一化 |
编码格式 | 仅支持 float,不支持 base64 |
请求示例
以下示例在单次请求中同时传入文本、图片和视频。模型会将多种模态的内容融合为一个向量,可用于图文检索、视频检索和多模态语义匹配等场景。
curl -X POST 'https://tokenhub.tencentmaas.com/v1/embeddings/multimodal' \\-H 'Authorization: Bearer YOUR_API_KEY' \\-H 'Content-Type: application/json' \\-d '{"model": "kinfra-vl-embedding-2b","input": [{"type": "text", "text": "一只白色猫坐在窗边"},{"type": "image_url", "image_url": {"url": "https://example.com/cat.png"}},{"type": "video_url", "video_url": {"url": "https://media.w3.org/2010/05/sintel/trailer.mp4"}}],"instructions": "生成适合图文检索的向量","encoding_format": "float"}'
import requestsurl = "https://tokenhub.tencentmaas.com/v1/embeddings/multimodal"headers = {"Authorization": "Bearer YOUR_API_KEY","Content-Type": "application/json"}payload = {"model": "kinfra-vl-embedding-2b","input": [{"type": "text", "text": "一只白色猫坐在窗边"},{"type": "image_url", "image_url": {"url": "https://example.com/cat.png"}},{"type": "video_url", "video_url": {"url": "https://media.w3.org/2010/05/sintel/trailer.mp4"}}],"instructions": "生成适合图文检索的向量","encoding_format": "float"}response = requests.post(url, headers=headers, json=payload)print(response.json())
async function main() {const response = await fetch('https://tokenhub.tencentmaas.com/v1/embeddings/multimodal', {method: 'POST',headers: {Authorization: 'Bearer YOUR_API_KEY','Content-Type': 'application/json'},body: JSON.stringify({model: 'kinfra-vl-embedding-2b',input: [{ type: 'text', text: '一只白色猫坐在窗边' },{ type: 'image_url', image_url: { url: 'https://example.com/cat.png' } },{ type: 'video_url', video_url: { url: 'https://media.w3.org/2010/05/sintel/trailer.mp4' } }],instructions: '生成适合图文检索的向量',encoding_format: 'float'})});console.log(await response.json());}main();
package mainimport ("bytes""encoding/json""fmt""io""net/http")func main() {body, err := json.Marshal(map[string]interface{}{"model": "kinfra-vl-embedding-2b","input": []map[string]interface{}{{"type": "text", "text": "一只白色猫坐在窗边"},{"type": "image_url", "image_url": map[string]string{"url": "https://example.com/cat.png"}},{"type": "video_url", "video_url": map[string]string{"url": "https://media.w3.org/2010/05/sintel/trailer.mp4"}},},"instructions": "生成适合图文检索的向量","encoding_format": "float",})if err != nil {panic(err)}req, err := http.NewRequest("POST","https://tokenhub.tencentmaas.com/v1/embeddings/multimodal",bytes.NewBuffer(body))if err != nil {panic(err)}req.Header.Set("Authorization", "Bearer YOUR_API_KEY")req.Header.Set("Content-Type", "application/json")resp, err := http.DefaultClient.Do(req)if err != nil {panic(err)}defer resp.Body.Close()data, err := io.ReadAll(resp.Body)if err != nil {panic(err)}fmt.Println(string(data))}
import okhttp3.*;import com.google.gson.Gson;import java.util.*;public class MultimodalEmbeddingQuickStart {public static void main(String[] args) throws Exception {Map<String, Object> body = new HashMap<>();body.put("model", "kinfra-vl-embedding-2b");List<Map<String, Object>> inputList = new ArrayList<>();inputList.add(Map.of("type", "text", "text", "一只白色猫坐在窗边"));inputList.add(Map.of("type", "image_url", "image_url", Map.of("url", "https://example.com/cat.png")));inputList.add(Map.of("type", "video_url", "video_url", Map.of("url", "https://media.w3.org/2010/05/sintel/trailer.mp4")));body.put("input", inputList);body.put("instructions", "生成适合图文检索的向量");body.put("encoding_format", "float");Request request = new Request.Builder().url("https://tokenhub.tencentmaas.com/v1/embeddings/multimodal").header("Authorization", "Bearer YOUR_API_KEY").header("Content-Type", "application/json").post(RequestBody.create(new Gson().toJson(body), MediaType.parse("application/json"))).build();try (Response response = new OkHttpClient().newCall(request).execute()) {System.out.println(response.body().string());}}}
响应示例
以下示例仅展示响应结构,向量值和 token 数以实际返回为准。
说明:
多模态向量接口会将单次请求中的文本、图片和视频融合为一个向量。响应中的
data 数组包含 1 个向量结果,index 固定为 0。{"object": "list","data": [{"object": "embedding","index": 0,"embedding": [0.0123, -0.0456, 0.0789]}],"model": "kinfra-vl-embedding-2b","usage": {"prompt_tokens": 1057,"total_tokens": 1057,"prompt_tokens_details": {"text_tokens": 12,"image_tokens": 1045,"video_tokens": 0}}}
响应参数
基础字段:
参数 | 类型 | 说明 |
object | String | 固定为 list |
model | String | 本次请求使用的模型 ID |
data | Array | 向量结果列表,包含 1 个融合向量 |
data[].object | String | 固定为 embedding |
data[].index | Integer | 固定为 0 |
data[].embedding | Array | 向量数组,浮点数格式 |
usage 字段:
参数 | 类型 | 说明 |
usage.prompt_tokens | Integer | 输入内容消耗的 token 总数 |
usage.total_tokens | Integer | 本次请求消耗的 token 总数 |
usage.prompt_tokens_details | Object | 输入 token 明细,按模态细分 |
usage.prompt_tokens_details.text_tokens | Integer | 文本输入消耗的 token 数 |
usage.prompt_tokens_details.image_tokens | Integer | 图片输入消耗的 token 数 |
usage.prompt_tokens_details.video_tokens | Integer | 视频输入消耗的 token 数 |
使用建议
批量处理时,建议控制单次请求的输入数量和输入长度,避免请求体过大。
在生产环境中,建议预先生成文档、图片或视频向量并存储到向量数据库中。查询时仅需生成查询向量并执行相似度检索。
价格说明
应用示例
文本语义搜索
以下示例展示如何使用文本向量模型实现语义搜索:先对知识库文档生成向量,再对用户查询生成向量,最后通过余弦相似度匹配最相关的文档。该方式适用于智能问答、知识库检索、FAQ 匹配等场景。
import numpy as npfrom openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://tokenhub.tencentmaas.com/v1")def cosine_similarity(a, b):denominator = np.linalg.norm(a) * np.linalg.norm(b)if denominator == 0:return 0return np.dot(a, b) / denominatordocuments = ["人工智能是计算机科学的一个分支","机器学习是实现人工智能的重要方法","深度学习是机器学习的一个子领域",]# 生成文档向量doc_resp = client.embeddings.create(model="kinfra-text-embedding-0.6b",input=documents)doc_embeddings = [item.embedding for item in doc_resp.data]# 生成查询向量query_resp = client.embeddings.create(model="kinfra-text-embedding-0.6b",input="什么是 AI?")query_embedding = query_resp.data[0].embedding# 计算相似度并排序similarities = [(i, cosine_similarity(query_embedding, doc_emb))for i, doc_emb in enumerate(doc_embeddings)]similarities.sort(key=lambda x: x[1], reverse=True)for i, score in similarities:print(f"相似度: {score:.3f} | 文档: {documents[i]}")
图片和视频 token 换算
多模态向量模型会将图片和视频转换为视觉 token,并在响应的
usage.prompt_tokens_details.image_tokens 和 usage.prompt_tokens_details.video_tokens 中返回对应用量。图片 token 换算
图片 token 数由图片分辨率决定。系统会先将图片缩放到模型支持的像素范围内,再按以下规则计算:
1. 将图片按 28 x 28 像素切分为 patch。
2. 按 2 x 2 patch 进行合并。
3. 合并后的 patch 数即为图片 token 数。
计算公式如下:
h_patches = floor(Height / 28)w_patches = floor(Width / 28)h_merge = floor(h_patches / 2)w_merge = floor(w_patches / 2)image_tokens = h_merge × w_merge
图片尺寸 | 计算过程 | image_tokens |
512 x 512 | 18 x 18 patch,合并后为 9 x 9 | 81 |
1024 x 1024 | 36 x 36 patch,合并后为 18 x 18 | 324 |
1280 x 720 | 45 x 25 patch,合并后为 22 x 12 | 264 |
说明:
图片会先缩放到模型支持的像素范围内。实际 token 数以接口响应中的
usage.prompt_tokens_details.image_tokens 为准。视频 token 换算
视频 token 数由采样帧数和每帧图片 token 数共同决定。系统会先按帧率对视频采样,再将每一帧按图片 token 规则计算。
计算方式如下:
采样帧数 N = min(视频时长(秒)× fps, max_frames)video_tokens ≈ N × tokens_per_frame
其中:
参数 | 说明 |
fps | 采样帧率,默认 1.0 |
max_frames | 最大采样帧数,当前为 64 |
tokens_per_frame | 每帧图片按图片 token 规则计算得到的 token 数 |
说明:
视频每帧的分辨率会受
total_pixels / N 约束。实际 token 数以接口响应中的 usage.prompt_tokens_details.video_tokens 为准。模型效果
文本向量模型(CMTEB)
模型 | 参数量 | Mean(Task) | Mean(Type) | 分类 | 聚类 | 配对分类 | 重排 | 检索 | STS |
kinfra-text-embedding-0.6b | 0.6B | 66.64 | 67.83 | 71.46 | 68.60 | 76.84 | 64.16 | 71.01 | 54.88 |
kinfra-text-embedding-4b | 4B | 72.63 | 73.95 | 75.55 | 78.15 | 83.29 | 68.26 | 77.02 | 61.41 |
多模态向量模型
模型 | 参数量 | MSCOCO_t2i | VisualNews_t2i | WebQA | EDIS | VisDial | Wiki-SS-NQ | 图文检索 mean | MMEB-V2 |
kinfra-vl-embedding-2b | 2B | 0.70 | 0.60 | 0.87 | 0.80 | 0.69 | 0.53 | 0.698 | 69.82 |
kinfra-vl-embedding-8b | 8B | 0.76 | 0.67 | 0.90 | 0.89 | 0.87 | 0.68 | 0.795 | 75.26 |
参考文档
语言模型调用概览
模型价格