向量模型

最近更新时间:2026-07-07 09:41:00

我的收藏

概述

向量模型可以将文本、图片等输入内容转换为向量表示,适用于语义检索、相似度计算、文本聚类、文本分类和图文检索等场景。
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
Python
Node.js
Go
Java
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 OpenAI

client = 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 main

import (
"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
Python
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
多模态输入列表,元素类型支持 textimage_urlvideo_url
input[].type
String
输入类型。取值:textimage_urlvideo_url
input[].text
String
文本内容。当 typetext 时填写。
input[].image_url
Object
图片地址对象。当 typeimage_url 时填写。
input[].image_url.url
String
图片 URL 或 base64 内容。
input[].video_url
Object
视频地址对象。当 typevideo_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 维。

使用限制

限制项
说明
多模态输入类型
仅支持 textimage_urlvideo_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
Python
Node.js
Go
Java
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 requests

url = "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 main

import (
"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 np
from openai import OpenAI

client = 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 0
return np.dot(a, b) / denominator

documents = [
"人工智能是计算机科学的一个分支",
"机器学习是实现人工智能的重要方法",
"深度学习是机器学习的一个子领域",
]

# 生成文档向量
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_tokensusage.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

参考文档