升级Langfuse SDK至3.6.1后，CallbackHandler遇SSL证书验证错误

问题核心 #

将Langfuse Python SDK从2.60.5升级到3.6.1后，在LangGraph中启用追踪时，使用自定义OpenAI BaseUrl+携带证书的httpx客户端出现SSL证书验证失败错误，但旧版本直接传参数可正常运行。

错误示例 #

SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain (_ssl.c:1006)

新旧版本代码对比 #

旧版本（2.60.5，正常运行）

import httpx
from langfuse.callback import CallbackHandler

# 带自定义证书的httpx客户端
client = httpx.Client(verify="/path/to/your/cert.pem")

# 初始化回调处理器
handler = CallbackHandler(
    public_key="YOUR_LANGFUSE_PUB_KEY",
    secret_key="YOUR_LANGFUSE_SEC_KEY",
    host="https://your-self-hosted-langfuse.com",
    client=client
)

新版本（3.6.1，报错）

import httpx
from langfuse.callback import CallbackHandler

client = httpx.Client(verify="/path/to/your/cert.pem")

handler = CallbackHandler(
    public_key="YOUR_LANGFUSE_PUB_KEY",
    secret_key="YOUR_LANGFUSE_SEC_KEY",
    host="https://your-self-hosted-langfuse.com",
    client=client  # 旧参数传递方式在3.x中失效
)

问题原因 #

Langfuse 3.x版本重构了客户端初始化逻辑，CallbackHandler不再直接接收httpx.Client实例作为参数，旧版本的参数传递方式被废弃，导致自定义证书配置未被正确应用到内部请求，触发SSL验证失败。

解决方案 #

针对3.6.1版本，有两种可靠的配置方式：

方式1：通过client_options直接传递SSL验证配置 #

from langfuse.callback import CallbackHandler

handler = CallbackHandler(
    public_key="YOUR_LANGFUSE_PUB_KEY",
    secret_key="YOUR_LANGFUSE_SEC_KEY",
    host="https://your-self-hosted-langfuse.com",
    client_options={
        "verify": "/path/to/your/cert.pem"
    }
)

方式2：手动初始化Langfuse客户端再关联回调 #

如果需要更复杂的httpx配置（比如代理、自定义headers），可以先创建Langfuse客户端，再基于它生成CallbackHandler：

import httpx
from langfuse import Langfuse
from langfuse.callback import CallbackHandler

# 自定义httpx客户端
client = httpx.Client(
    verify="/path/to/your/cert.pem",
    proxies="http://your-proxy.com:8080"  # 示例额外配置
)

# 初始化Langfuse客户端
langfuse_client = Langfuse(
    public_key="YOUR_LANGFUSE_PUB_KEY",
    secret_key="YOUR_LANGFUSE_SEC_KEY",
    host="https://your-self-hosted-langfuse.com",
    client=client
)

# 创建关联回调处理器
handler = CallbackHandler(langfuse=langfuse_client)

验证方法 #

1. 替换代码中的密钥、主机地址和证书路径
2. 运行LangGraph流程，检查是否仍有SSL错误
3. 登录Langfuse后台确认追踪数据正常上报

内容的提问来源于stack exchange，提问作者Parth Sekar