使用 Litefuse 实现 BytePlus 的可观测性
本指南将介绍如何将 BytePlus 与 Litefuse 集成。BytePlus 的对话、语言与代码、图像和 embedding API 端点与 OpenAI 的 API 完全兼容。这让我们可以使用 Litefuse 的 OpenAI 替换方案来追踪应用的所有部分。
什么是 BytePlus？ BytePlus 是由 字节跳动 开发的一套 AI 驱动的 API 和服务，包括语音、视频和推荐技术。Litefuse 与 BytePlus 集成，可以追踪和评估使用 BytePlus 工具的 LLM 工作流，从而在生成和用户交互过程中实现可观测性。
什么是 Litefuse？ Litefuse 是一个开源的 AI Agent 可观测性与评估平台，帮助团队追踪 API 调用、监控性能并调试 AI 应用中的问题。
注意： 你也可以通过 OpenAI 适配器在 Litefuse Playground 和 LLM-as-a-Judge 评估中使用 BytePlus 模型。在 Litefuse 中设置 LLM Connection 的方法见这里。
第一步：安装依赖
确保已安装所需的 Python 包：
%pip install openai langfuse第二步：设置环境变量
接下来，设置你的 Litefuse API Key。你可以通过注册免费的 Litefuse Cloud 账户或自托管 Litefuse 来获取这些密钥。这些环境变量对于 OpenAI 替换方案 进行身份认证并向你的 Litefuse 项目发送数据来说至关重要。
关于如何创建用于模型服务的 BytePlus API Key，请参阅此处。
import os
# Get keys for your project from the project settings page: https://litefuse.cloud
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
os.environ["LANGFUSE_BASE_URL"] = "https://litefuse.cloud"
# Get your BytePlus API key from the project settings page
os.environ["ARK_API_KEY"] = "***"第三步：Litefuse OpenAI 替换方案
在这一步，我们通过 from langfuse.openai import openai 使用原生的 OpenAI 替换方案。
要开始通过 OpenAI 客户端库使用 BytePlus 模型，请将你的 BytePlus API Key 传给 api_key 选项，并将 base_url 改为 https://ark.ap-southeast.bytepluses.com/api/v3：
# instead of import openai:
from langfuse.openai import openai
client = openai.OpenAI(
api_key=os.environ.get("ARK_API_KEY"),
base_url="https://ark.ap-southeast.bytepluses.com/api/v3",
)注意： OpenAI 替换方案与 低层级 Litefuse Python SDK 以及 @observe() 装饰器 完全兼容，可以追踪应用的所有部分。
第四步：运行示例
下面的代码演示了如何使用受追踪的 OpenAI 客户端通过 BytePlus 调用 Kimi K2 模型。所有 API 调用都会被 Litefuse 自动追踪。
# Non-streaming:
print("----- standard request -----")
completion = client.chat.completions.create(
# Specify the Ark Inference Point ID that you created, which has been changed for you here to your Endpoint ID
model="kimi-k2-250711",
messages=[
{"role": "system", "content": "You're an AI assistant"},
{"role": "user", "content": "What is Litefuse?"},
],
name = "BytePlus-Generation" # Optional: Set the name of the generation in Litefuse
)
print(completion.choices[0].message.content)# Streaming:
print("----- streaming request -----")
stream = client.chat.completions.create(
# Specify the Ark Inference Point ID that you created, which has been changed for you here to your Endpoint ID
model="kimi-k2-250711",
messages=[
{"role": "system", "content": "You're an AI assistant"},
{"role": "user", "content": "What is Litefuse?"},
],
name = "BytePlus-Generation", # Optional: Set the name of the generation in Litefuse
# Whether the response content is streamed back
stream=True,
)
for chunk in stream:
if not chunk.choices:
continue
print(chunk.choices[0].delta.content, end="")
print()第五步：在 Litefuse 中查看 trace
运行示例模型调用后，你可以在 Litefuse 中查看 trace。你将看到关于 BytePlus API 调用的详细信息，包括：
- 请求参数（模型、messages、temperature 等）
- 响应内容
- token 使用统计
- 延迟指标
Interoperability with the Python SDK
You can use this integration together with the Litefuse SDKs to add additional attributes to the observation.
The @observe() decorator provides a convenient way to automatically wrap your instrumented code and add additional attributes to the observation.
from langfuse import observe, propagate_attributes, get_client
langfuse = get_client()
@observe()
def my_llm_pipeline(input):
# Add additional attributes (user_id, session_id, metadata, version, tags) to all spans created within this execution scope
with propagate_attributes(
user_id="user_123",
session_id="session_abc",
tags=["agent", "my-observation"],
metadata={"email": "user@litefuse.ai"},
version="1.0.0"
):
# YOUR APPLICATION CODE HERE
result = call_llm(input)
return result
# Run the function
my_llm_pipeline("Hi")Learn more about using the Decorator in the Langfuse SDK instrumentation docs.
Troubleshooting
No observations appearing
First, enable debug mode in the Python SDK:
export LANGFUSE_DEBUG="True"Then run your application and check the debug logs:
- OTel observations appear in the logs: Your application is instrumented correctly but observations are not reaching Litefuse. To resolve this:
- Call
langfuse.flush()at the end of your application to ensure all observations are exported. - Verify that you are using the correct API keys and base URL.
- Call
- No OTel spans in the logs: Your application is not instrumented correctly. Make sure the instrumentation runs before your application code.
Unwanted observations in Litefuse
The Langfuse SDK is based on OpenTelemetry. Other libraries in your application may emit OTel spans that are not relevant to you. These still count toward your billable units, so you should filter them out. See Unwanted spans in Litefuse for details.
Missing attributes
Some attributes may be stored in the metadata object of the observation rather than being mapped to the Litefuse data model. If a mapping or integration does not work as expected, please raise an issue on GitHub.
Next Steps
Once you have instrumented your code, you can manage, evaluate and debug your application: