将 Litefuse 与 Semantic Kernel 集成
本 notebook 提供一份分步指南，介绍如何将 Litefuse 与 Semantic Kernel 集成，从而获得对 LLM 应用的可观测性与调试能力。跟随本教程，你将学会如何使用 Litefuse 追踪你的 Semantic Kernel 应用，在一处管理 prompt，并对应用进行评估，让其达到生产可用水平。
什么是 Semantic Kernel？ Semantic Kernel（GitHub）是微软推出的一款强大的开源 SDK。它便于将 LLM 与 C#、Python、Java 等主流编程语言结合。Semantic Kernel 让开发者能够通过无缝集成 AI 服务、数据源与自定义逻辑，构建复杂的 AI 应用，加速企业级 AI 解决方案的落地。
什么是 Litefuse？ Litefuse 是一个开源的 LLM 可观测性平台，提供面向 AI 应用的强大追踪与监控能力。Litefuse 通过原生集成、OpenTelemetry 以及专用 SDK，与多种工具和框架对接，帮助开发者调试、分析并优化 AI 系统。
快速开始
下面我们通过一个实用示例，演示如何使用 Semantic Kernel，并将其与 Litefuse 集成以获得完整的追踪能力。
第 1 步：安装依赖
%pip install langfuse openlit semantic-kernel第 2 步：配置 Langfuse SDK
接下来配置你的 Litefuse API Key。你可以通过注册免费的 Litefuse Cloud 账号获取这些 Key，或者自托管 Litefuse。这些环境变量是 Langfuse 客户端进行认证并将数据发送到你 Litefuse 项目的必要条件。
import os
# 从项目设置页面获取你项目的 Key：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"
# 你的 OpenAI key
os.environ["OPENAI_API_KEY"] = "sk-proj-..."
os.environ["OPENAI_CHAT_MODEL_ID"] = "gpt-4o"设置好环境变量后，我们就可以初始化 Langfuse 客户端了。get_client() 会使用环境变量中的凭证初始化 Langfuse 客户端。
from langfuse import get_client
langfuse = get_client()
# 验证连接
if langfuse.auth_check():
print("Langfuse client is authenticated and ready!")
else:
print("Authentication failed. Please check your credentials and host.")Langfuse client is authenticated and ready!
第 3 步：初始化 OpenLit 用于 Instrumentation
接下来初始化 OpenLit instrumentation SDK。OpenLit 会自动为 Semantic Kernel 添加 instrumentation，并将 OpenTelemetry（OTel）span 导出到 Litefuse。
import openlit
# 初始化 OpenLIT instrumentation。设置 disable_batch=True 以便立即处理 trace。同时使用 langfuse tracer。
openlit.init(tracer=langfuse._otel_tracer, disable_batch=True)第 4 步：基础 Semantic Kernel 应用
我们来创建一个简洁的 Semantic Kernel 应用。在这个示例中，一个 Assistant agent 会回答用户的问题。它将作为演示 Litefuse 追踪的基础。
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
kernel = Kernel()
kernel.add_service(
OpenAIChatCompletion(),
)from semantic_kernel.prompt_template import InputVariable, PromptTemplateConfig
prompt = """{{$input}}
Answer the question above.
"""
prompt_template_config = PromptTemplateConfig(
template=prompt,
name="summarize",
template_format="semantic-kernel",
input_variables=[
InputVariable(name="input", description="The user input", is_required=True),
]
)
summarize = kernel.add_function(
function_name="summarizeFunc",
plugin_name="summarizePlugin",
prompt_template_config=prompt_template_config,
)第 5 步：运行应用
Semantic Kernel 应用搭建好后，用一个示例问题来调用它并打印响应。OpenLit 会自动捕获这次交互，并将 trace 数据发送到 Litefuse。
input_text = "What is Litefuse?"
summary = await kernel.invoke(summarize, input=input_text)
print(summary)第 6 步：在 Litefuse 中查看 Trace
应用执行结束后，打开你的 Litefuse Trace 表。你会看到应用执行的详细 trace，包括 LLM 调用、输入、输出以及性能指标。下面这张截图展示了一条 trace 在 Litefuse 中的样子：
如需查看在线示例，可以浏览这条公开 trace：Litefuse Semantic Kernel Trace 示例
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: