跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://simplellmfunc.cn/llms.txt

Use this file to discover all available pages before exploring further.

​
可观测性

SimpleLLMFunc 集成了 Langfuse，用于追踪 LLM 生成、工具调用和 Agent 会话。

​
设置

​
1. 安装（已包含在 SimpleLLMFunc 中）

Langfuse 客户端已内置，无需额外安装。

​
2. 配置环境变量

# .env
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com
LANGFUSE_ENABLED=true
LANGFUSE_EXPORT_ALL_SPANS=true

​
3. 正常使用即可

配置完成后，追踪是自动进行的。每次被 @llm_function 和 @llm_chat 装饰的调用都会创建：
  • 一个 Trace，对应完整的调用生命周期
  • Generation 记录，对应每次 LLM 调用
  • Span 记录，对应每次工具执行

​
追踪内容

组件Langfuse 实体包含内容
@llm_function 调用Trace完整的调用生命周期
@llm_chat 调用Trace完整的 ReAct 循环
每次 LLM API 调用Generation输入/输出消息、token 数、延迟
每次工具执行Span工具名称、参数、结果、耗时
ReAct 迭代Span迭代边界

​
Trace ID

每次调用都会获得一个唯一的 trace_id，贯穿所有嵌套操作： 
from SimpleLLMFunc.logger import get_current_trace_id

# 在工具或自定义代码内部
trace_id = get_current_trace_id()

​
自定义 Trace 名称

Trace 名称默认为被装饰函数的函数名。可通过以下方式覆盖： 
@llm_function(llm_interface=llm)
async def my_func(text: str) -> str:
    """Process text."""
    pass

# 该 trace 在 Langfuse 中将命名为 "my_func"

​
刷新

观测数据会被批量异步发送。在关闭时可强制刷新： 
from SimpleLLMFunc.observability import flush_all_observations

await flush_all_observations()

​
禁用

设置 LANGFUSE_ENABLED=false 或不配置密钥即可。框架会优雅降级——不会报错，只是不产生 trace。

​
日志级别

独立控制框架日志： 
LOG_LEVEL=WARNING   # 推荐：抑制内部的冗余日志
LOG_DIR=logs        # 文件输出位置
可用级别：DEBUG、INFO、WARNING、ERROR、CRITICAL。 仅在排查框架行为时使用 DEBUG。生产环境推荐使用 WARNING 作为默认级别。