QianfanEmbeddingsEndpoint调用时返回401错误如何解决？

Question

QianfanEmbeddingsEndpoint调用返回401错误，通常表示身份认证失败。常见原因有三：一是`qwen_api_key`或`qwen_secret_key`未正确配置（注意非Access Token），二是密钥已过期、被禁用或权限不足（需在千帆控制台确认「Embedding」服务已开通且密钥具备`qwen:embedding:invoke`权限）；三是请求头中`Authorization`字段缺失或格式错误（应为`Bearer `，而非`Basic`或其他）。此外，环境变量`QWEN_API_KEY`/`QWEN_SECRET_KEY`未生效、SDK版本过旧（建议升级至`qwen==1.2.0+`）、或误用模型服务密钥（如将LLM密钥用于Embedding）亦会导致该问题。排查时建议先用`curl`直连千帆OpenAPI验证密钥有效性，并检查日志中实际发送的鉴权头。务必避免硬编码密钥，推荐使用安全凭证管理方式。

Answer 1

一、表层现象：401 Unauthorized 是什么？

HTTP 401状态码明确表示“未授权（Unauthorized）”，即客户端请求缺乏有效身份凭证，服务端拒绝提供资源。对 QianfanEmbeddingsEndpoint 而言，该错误并非网络不通或模型不可用，而是鉴权链路在第一关即被拦截——它不涉及模型推理逻辑，只关乎「你是谁」和「你是否有权调用 Embedding 服务」。

值得注意的是，千帆平台严格区分服务类型与密钥权限域：LLM 密钥 ≠ Embedding 密钥，即使同一账号下生成的 API Key，若未显式授予 qwen:embedding:invoke 权限，调用 Embedding 接口必然返回 401。

二、中层根因：三类高频认证失效场景

• 配置缺失或错位：环境变量 QWEN_API_KEY/QWEN_SECRET_KEY 未加载（如 .env 未 source、Docker 容器未透传、K8s Secret 挂载路径错误）；或代码中误写为 qwen_api_key（下划线命名）但 SDK 实际读取 QWEN_API_KEY（全大写+下划线）；更常见的是混淆了「Access Token」（用于 OAuth 流程）与千帆平台颁发的「API Key/Secret Key」对。
• 密钥生命周期异常：密钥在千帆控制台被手动禁用、主动轮换后旧密钥失效、或因安全策略自动过期（默认有效期 180 天）；权限未绑定至 Embedding 服务——需进入【API 密钥管理】→【编辑权限】→ 勾选 qwen:embedding:invoke，而非仅开通 LLM 或通用权限。
• 协议层鉴权污染：SDK 或自定义 HTTP Client 错误构造 Authorization Header，例如：
  ❌ Authorization: Basic base64(...)
  ❌ Authorization: Bearer <api_key>（漏掉 secret_key）
  ✅ 正确格式：Authorization: Bearer <api_key>:<secret_key>（冒号拼接，Base64 编码前原始字符串）

三、深层验证：结构化排查路径（含工具链）

以下为推荐的渐进式验证流程，支持快速定位断点：

# 1. 直连 OpenAPI（绕过 SDK）验证密钥有效性
curl -X POST "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/embeddings/qwen-embedding" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${QWEN_API_KEY}:${QWEN_SECRET_KEY}" \
  -d '{
    "input": ["hello world"]
  }'

# 2. 检查实际发出的请求头（Python 示例）
import logging
logging.basicConfig(level=logging.DEBUG)
import http.client as http_client
http_client.HTTPConnection.debuglevel = 1

四、技术栈兼容性与演进约束

组件	兼容要求	风险提示
qwen SDK	≥ v1.2.0	v1.1.x 及更早版本存在 Authorization 构造缺陷，将 secret_key 误作 bearer token 主体
LangChain 集成	langchain-community ≥ 0.3.0	旧版 QianfanEmbeddingsEndpoint 类未校验权限字段，静默忽略密钥错误

五、生产级安全实践规范

硬编码密钥是重大安全反模式。企业级部署应强制采用：

• 云平台原生凭证服务：AWS Secrets Manager / 阿里云 KMS / 千帆平台内置「密钥托管」功能
• 运行时注入机制：Kubernetes 使用 envFrom.secretRef + initContainer 解密注入
• 最小权限原则：为 Embedding 服务单独创建专用密钥，禁止复用 LLM 密钥，权限粒度精确到 qwen:embedding:invoke

六、典型错误日志对照表

graph TD
    A[收到401] --> B{检查环境变量}
    B -->|缺失/拼写错误| C[设置QWEN_API_KEY/QWEN_SECRET_KEY]
    B -->|存在| D{调用curl直连}
    D -->|成功| E[SDK版本或Header构造问题]
    D -->|失败| F[密钥失效/权限不足/服务未开通]
    F --> G[登录千帆控制台检查]
    G --> H[确认Embedding服务已开通]
    G --> I[确认密钥状态为启用]
    G --> J[确认权限含qwen:embedding:invoke]

七、终极验证脚本（Python + requests）

以下脚本可嵌入 CI/CD 流水线，在部署前自动校验 Embedding 认证链：

import os
import requests
import base64

def validate_qwen_embedding_auth():
    api_key = os.getenv("QWEN_API_KEY")
    secret_key = os.getenv("QWEN_SECRET_KEY")
    if not (api_key and secret_key):
        raise EnvironmentError("QWEN_API_KEY or QWEN_SECRET_KEY missing")

    auth_str = f"{api_key}:{secret_key}"
    auth_header = f"Bearer {base64.b64encode(auth_str.encode()).decode()}"

    resp = requests.post(
        "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/embeddings/qwen-embedding",
        headers={"Authorization": auth_header, "Content-Type": "application/json"},
        json={"input": ["test"]},
        timeout=10
    )
    assert resp.status_code == 200, f"Auth failed: {resp.status_code} {resp.text}"
    print("✅ Embedding authentication validated successfully.")