Embedding 向量模型

阿里云百炼在 AI Gateway 中支持文本 Embedding 和多模态 Embedding。两类接口的 Endpoint 和请求体不同。

一、接口总览

类型	适用模型	Endpoint
文本 Embedding	Qwen Text Embedding V4 等	`https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/embeddings` https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/embeddings
多模态 Embedding	`qwen3-vl-embedding` qwen3-vl-embedding	`https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding` https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding

文本 Embedding 使用 OpenAI 兼容协议；Qwen3 VL Embedding 使用 DashScope 服务化多模态向量协议。

二、文本 Embedding

请求地址

POST https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/embeddings

请求头：

Authorization: Bearer <API_KEY> Content-Type: application/json

请求示例

curl -X POST "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/embeddings" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen/text-embedding-v4", "input": [ "AI Gateway 支持统一模型调用。", "模型路由可以按价格、吞吐或延迟策略执行。" ], "encoding_format": "float" }'

Python 示例：

from openai import OpenAI client = OpenAI( base_url="https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1", api_key="<your-api-key>", ) response = client.embeddings.create( model="qwen/text-embedding-v4", input=[ "AI Gateway 支持统一模型调用。", "模型路由可以按价格、吞吐或延迟策略执行。", ], encoding_format="float", ) vectors = [item.embedding for item in response.data] print(len(vectors), len(vectors[0]))

请求字段

字段	类型	必填	说明
`model` model	string	是	Embedding 模型名称。以模型广场详情页为准，例如 `qwen/text-embedding-v4` qwen/text-embedding-v4 。
`input` input	string / array	是	需要向量化的文本。可以传单条字符串，也可以传字符串数组批量处理。
`encoding_format` encoding_format	string	否	向量编码格式，常用 `float` float 。
`dimensions` dimensions	integer	否	输出向量维度。仅模型支持可变维度时可用。
`user` user	string	否	终端用户标识，可用于业务侧审计或追踪。

响应字段

{ "object": "list", "data": [ { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, 0.0789] } ], "model": "qwen/text-embedding-v4", "usage": { "prompt_tokens": 20, "total_tokens": 20 } }

字段	说明
`data[].embedding` data[].embedding	向量数组。
`data[].index` data[].index	与输入数组的位置对应。
`usage.prompt_tokens` usage.prompt_tokens	输入 Token 数。
`usage.total_tokens` usage.total_tokens	总 Token 数。

三、Qwen3 VL Embedding

qwen3-vl-embedding

qwen3-vl-embedding

适合对图片、文本或图文组合进行向量化，可用于以文搜图、以图搜图、图文混合检索等场景。

请求地址

POST https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding

请求头：

Authorization: Bearer <API_KEY> Content-Type: application/json

文本向量示例

curl -X POST "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/api/v1/services/embeddings/multimodal-embedding/multimodal-embedding" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen3-vl-embedding", "input": { "contents": [ { "text": "一张白色运动鞋的商品主图" } ] } }'

图片向量示例

图文组合向量示例

请求字段

字段	类型	必填	说明
`model` model	string	是	固定使用模型广场中的多模态 Embedding 模型名称，例如 `qwen3-vl-embedding` qwen3-vl-embedding 。
`input` input	object	是	输入对象。
`input.contents` input.contents	array	是	待向量化内容数组。
`input.contents[].text` input.contents[].text	string	否	文本内容。
`input.contents[].image` input.contents[].image	string	否	图片 URL。
`parameters` parameters	object	否	扩展参数。具体支持字段以模型详情页为准。

注意：

```
text
```
text
和
```
image
```
image
可单独使用，也可组合使用。
图片 URL 需要模型服务可访问。
生产环境中建议将图片上传到稳定可访问的对象存储，再传入 URL。

四、向量库接入建议

向量化后通常会写入向量数据库或搜索引擎。建议遵循以下原则：

同一个索引中的入库向量和查询向量必须使用同一个模型。
如果模型支持自定义
```
dimensions
```
dimensions
，建库前必须固定维度，后续不要随意修改。
文本检索和图片检索是否可混用，取决于模型是否将文本和图片映射到同一向量空间。
入库时保存原文、图片 URL、业务主键、模型名、向量维度和生成时间，方便重建索引。
批量向量化时要控制单次输入条数，避免请求体过大或超时。

五、常见错误

问题	可能原因	处理方式
向量维度与向量库不一致	更换了模型或 `dimensions` dimensions	使用同一模型重新建库或重建索引
图片无法向量化	图片 URL 不可访问、格式不支持、文件过大	换成公网可访问 URL，并压缩到模型支持范围
检索效果不稳定	入库文本过短、噪声多、模型不一致	清洗文本，增加关键字段，确保查询和入库模型一致
批量请求失败	单次输入过多或请求体过大	分批请求，并添加重试逻辑

联系我们