开放能力导航
首页/阿里云百炼/调用手册
阿里云百炼调用手册

生成 text-embedding-v4 检索向量

将中文文本转换成指定维度的向量，为自建语义索引提供输入。

官方资料核对 2026-10-15示例代码，未进行真实接口实测
← 返回平台功能

接入准备

  • 北京地域的通用 Key 已获得 text-embedding-v4 调用权限；自行准备向量存储。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行；密钥不应放进公开网页。

DASHSCOPE_API_KEY
百炼通用模型 API Key；不要误用 Token Plan 专属 Key。
DASHSCOPE_WORKSPACE_ID
来自百炼控制台业务空间详情；虚构值，需替换为北京地域真实空间 ID。
终端
export DASHSCOPE_API_KEY='replace_with_bailian_api_key'
export DASHSCOPE_WORKSPACE_ID='example-workspace-id'

以上 export 适用于 macOS / Linux 的终端，在同一终端内运行后续代码。Python 示例保存为 request.py 后执行 python3 request.py。

调用步骤

  1. 01

    登录阿里云百炼控制台，按提示完成实名认证并同意服务协议；本例限定华北2（北京）地域。

  2. 02

    在 API Key 管理创建通用 API Key，选择归属业务空间；若用 RAM 用户，确认它有空间和模型权限，若选自定义权限，将目标模型纳入允许范围。

  3. 03

    在业务空间详情取得空间 ID，设置 DASHSCOPE_WORKSPACE_ID；将该空间、该地域的 Key 放入 DASHSCOPE_API_KEY。

  4. 04

    本例使用官方推荐的空间专属域名。旧北京 dashscope.aliyuncs.com 域名目前仍可使用；其他地域不能仅更换 Key 而保留北京接入域名。

  5. 05

    执行前在模型广场核对示例 model 对当前空间已授权，检查额度及用完即停设置；本页代码只在自己的服务端运行。

  6. 06

    本例用 dimensions=256。让文档端和查询端统一使用 text-embedding-v4、相同维度，不能与其他向量模型直接混用。

调用 01

批量生成文本向量

使用兼容 /embeddings 同步接口；本例两条短文本符合当前 v4 批量上限。

POSThttps://${DASHSCOPE_WORKSPACE_ID}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings

请求头

Authorization
Bearer ${DASHSCOPE_API_KEY}
Content-Type
application/json

参数说明

参数表可左右滑动，查看完整说明。

字段 / 位置类型 / 必填说明
model请求体string必填固定 text-embedding-v4；不要把聊天模型名填到向量接口。
input请求体string[]必填输入文本列表；v4 当前单次最多 10 条，每条最多 8,192 Token。
dimensions请求体integer可选v4 支持 2048、1536、1024（默认）、768、512、256、128、64；本例 256。
encoding_format请求体string可选本例 float。不同新旧网关对 base64 的行为有差异，不能假设设置 base64 就必定返回字符串。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误，业务状态还需按下方返回示例核对。

cURL
cat > request-body.json <<'JSON'
{
  "model": "text-embedding-v4",
  "input": [
    "如何发送企业通知",
    "如何读取电子表格"
  ],
  "dimensions": 256,
  "encoding_format": "float"
}
JSON

# 执行后核对返回 JSON 的业务状态；HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://${DASHSCOPE_WORKSPACE_ID}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings" \
  --header "Authorization: Bearer ${DASHSCOPE_API_KEY}" \
  --header "Content-Type: application/json" \
  --data-binary @request-body.json
Python 3
import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://${DASHSCOPE_WORKSPACE_ID}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings")
headers = {
    "Authorization": expand("Bearer ${DASHSCOPE_API_KEY}"),
    "Content-Type": expand("application/json"),
}
body = {
    "model": "text-embedding-v4",
    "input": [
        "如何发送企业通知",
        "如何读取电子表格",
    ],
    "dimensions": 256,
    "encoding_format": "float",
}
data = json.dumps(body, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(url, data=data, headers=headers, method="POST")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
Node.js
// Node.js 22+，保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://${DASHSCOPE_WORKSPACE_ID}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/embeddings");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${DASHSCOPE_API_KEY}",
  "Content-Type": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const body = {
  "model": "text-embedding-v4",
  "input": [
    "如何发送企业通知",
    "如何读取电子表格"
  ],
  "dimensions": 256,
  "encoding_format": "float"
};
const response = await fetch(url, {
  method: "POST",
  headers,
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方字段整理的响应结构示意，ID、文本和数字均为虚构，非接口实测结果。数组为展示仅留前三个数字，实际本例应为 256 维；index 对应输入条目，不能拿示意数组做检索。 以下为结构示意，非本站实测结果。

JSON
{
  "id": "example_embedding_id",
  "object": "list",
  "model": "text-embedding-v4",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.014,
        -0.007,
        0.021
      ]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [
        0.018,
        -0.011,
        0.004
      ]
    }
  ],
  "usage": {
    "total_tokens": 20
  }
}

常见错误与排查

HTTP 401 InvalidApiKey / invalid_api_keyKey 错误或 Key 与接入地址不匹配。
检查环境变量、所属空间/地域；不要混用 Token Plan 专属 Key 和通用 Base URL。
HTTP 403 Model.AccessDenied业务空间无权调用目标模型。
核对空间授权、自定义 Key 模型范围及模型是否需要申请；模型名存在不代表账号已获准使用。
HTTP 429 Throttling.RateQuota调用次数达到 RPS/RPM 上限。
降低并发、平滑调度并退避；不要无限重试。
HTTP 429 Throttling.AllocationQuota / insufficient_quotaToken 用量达到 TPS/TPM 等分配上限。
缩短输入、降低并发，查看该模型的额度；与账户欠费和 Token Plan 次数限制分别排查。
HTTP 400输入内容、批次数量或维度不符合当前模型要求。
限制为非空文本并核对 v4 的 10 条、8192 Token 与允许维度；不要把其他 embedding 型号限制套用过来。

调用注意

  • 该向量接口不会创建知识库、切分长文档或配置检索权限，这些步骤由应用或独立知识库产品完成。
  • 此模型当前兼容响应 usage 仅包含 total_tokens；不要硬性要求出现 prompt_tokens。
  • 文本变更后需重新生成相应向量；改变模型或维度通常要求重建索引。
文本向量同步接口、模型与价格百炼 HTTP/业务错误码

注意事项

  • 核验日北京 text-embedding-v4 同步标准调用为每千输入 Token 0.0005 元；Batch 和其他地域规则需分别核对。
  • 新人免费额度按模型和期限计算，不覆盖向量数据库等外部资源费用；用量以接口 usage 和账单记录核对。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码，覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
  2. 02
  3. 03
  4. 04
  5. 05
    百炼 HTTP/业务错误码核验日期 2026-10-15

阿里云百炼的其他调用手册

使用兼容接口完成文本问答

← 返回阿里云百炼的全部功能