LangChain4j调用智谱AI时API密钥认证失败

Question

在使用 LangChain4j 调用智谱AI（Zhipu AI）API 时，常因 API 密钥格式错误或鉴权方式不匹配导致认证失败。典型问题包括：将 API Key 错误地拼接在请求头中、未按智谱AI要求设置 `Authorization: Bearer ${apiKey}` 格式，或使用了过期、受限的密钥。此外，LangChain4j 默认的 HttpClient 配置可能未正确传递认证信息，需显式配置 Headers 和 Base URL。确保密钥具有对应接口调用权限，并检查环境变量或配置文件中的密钥是否被意外转义或截断，是排查此类问题的关键步骤。

Answer 1

使用 LangChain4j 调用智谱AI API 的认证问题深度解析

1. 问题背景与常见现象

在集成 LangChain4j 框架调用 智谱AI（Zhipu AI）API 时，开发者频繁遭遇 401 Unauthorized 或 403 Forbidden 错误。这些错误多数源于认证机制配置不当，尤其是在密钥管理、请求头构造和客户端配置层面。

典型表现包括：

• 返回错误码：{"error": {"type": "invalid_request_error", "message": "Invalid authorization header."}}
• 日志中显示 Bearer token 缺失或格式不正确
• 即使密钥正确，仍提示权限不足或接口不可访问

这些问题不仅影响开发效率，还可能导致生产环境服务中断。

2. 鉴权机制原理分析

智谱AI遵循标准的 OAuth 2.0 风格的 Bearer Token 认证方式，要求所有请求必须携带如下格式的 HTTP 请求头：

Authorization: Bearer <your_api_key>

其中：

字段	说明
Authorization	HTTP 标准头部字段
Bearer	认证方案类型，固定值
<your_api_key>	由 Zhipu AI 控制台生成的实际密钥字符串

若该头部缺失、拼写错误或结构不符（如使用 API-Key: xxx），服务器将拒绝请求。

3. LangChain4j 默认行为与潜在陷阱

LangChain4j 使用内部封装的 HttpClient 发起远程调用，默认并不会自动注入 Authorization 头部，除非显式配置。以下是常见误区：

1. 直接将 API Key 作为 URL 参数传递（不安全且不符合规范）
2. 误认为 ZhipuAiChatModel.builder().apiKey("...") 会自动处理头部设置（实际依赖底层 client 行为）
3. 未自定义 RetryingConfigurableHttpClient 或 OkHttpClient 实例以添加 headers

示例代码中常见的错误配置：

ZhipuAiChatModel model = ZhipuAiChatModel.builder()
    .apiKey("sk-xxxxx") // 此处仅设置属性，但未确保 header 注入
    .build();

4. 正确配置 LangChain4j 客户端的完整方案

为确保认证信息正确传递，需显式构建支持自定义 Header 的 HTTP 客户端。推荐使用 OkHttp 作为底层实现：

import dev.langchain4j.model.zhipu.ZhipuAiChatModel;
import okhttp3.OkHttpClient;
import okhttp3.Request;

OkHttpClient httpClient = new OkHttpClient.Builder()
    .addInterceptor(chain -> {
        Request original = chain.request();
        Request request = original.newBuilder()
            .header("Authorization", "Bearer " + System.getenv("ZHIPU_API_KEY"))
            .method(original.method(), original.body())
            .build();
        return chain.proceed(request);
    })
    .build();

ZhipuAiChatModel model = ZhipuAiChatModel.builder()
    .apiKey(System.getenv("ZHIPU_API_KEY")) // 可选，用于日志记录等
    .httpClient(httpClient)
    .baseUrl("https://open.bigmodel.cn/api/paas/v4/") // 明确指定 base url
    .build();

此方案通过拦截器确保每个请求都附加正确的 Authorization 头。

5. 密钥管理与环境变量陷阱

即便代码逻辑正确，若 API Key 来源存在问题，依然会导致失败。以下为常见隐患：

• 环境变量中包含引号导致转义：export ZHIPU_API_KEY="sk-abc123" → 实际读取为带引号字符串
• 配置文件换行截断（如 .env 文件末尾无换行符）
• CI/CD 环境中密钥被 masking 或加密解密失败
• 使用了测试密钥调用生产接口，权限受限

建议采用如下校验流程：

graph TD A[获取API Key] --> B{是否从环境变量加载?} B -- 是 --> C[打印长度前缀调试] B -- 否 --> D[检查配置文件格式] C --> E[验证无多余空格/引号] D --> E E --> F[调用 /v4/models 测试连通性] F --> G{返回200?} G -- 是 --> H[认证成功] G -- 否 --> I[检查控制台密钥状态]

6. 权限模型与接口匹配验证

智谱AI平台对不同密钥授予差异化权限，例如：

密钥类型	可调用接口	速率限制
Free Tier	glm-4, glm-4v	10 QPS
Pro Tier	glm-4-plus, codegeex	50 QPS
Sandbox	仅测试模型	1 QPS

若尝试调用未授权模型（如用免费密钥调用 glm-4-plus），即使认证通过也会返回 403。应通过 Zhipu AI 控制台确认当前密钥绑定的服务范围。

7. 日志与调试策略

启用详细日志有助于快速定位问题。可在 logback.xml 中增加：

<logger name="dev.langchain4j" level="DEBUG"/>
<logger name="okhttp3" level="DEBUG"/>

观察输出中是否包含：

• Outgoing request: POST https://open.bigmodel.cn/api/paas/v4/chat/completions
• Header: Authorization: Bearer sk-...
• Response: 401 Unauthorized - Invalid bearer token

结合 WireMock 或 Charles 抓包工具，可进一步验证请求真实内容。