SimpleLLMFunc 是什么?
SimpleLLMFunc 是一个轻量级的大语言模型（Large Language Model, LLM）应用开发框架，旨在简化 LLM 在应用中的集成过程。本框架的设计理念是“LLM as Function, Prompt as Code”，提供类型安全的装饰器，让开发者能以一种自然、直观的方式利用大语言模型的能力。
LLM as Function
用 Python 函数签名和返回类型组织 LLM 能力，而不是手写大量样板调用代码。
Prompt as Code
让 DocString 成为 Prompt 本身，减少 prompt 与业务代码分离带来的维护成本。
类型安全 + 工具能力
同时支持结构化返回、工具调用、多模态输入输出和事件流。
为什么需要 SimpleLLMFunc?
在开发基于大语言模型的应用时，我们常常面临以下挑战：
- 需要不断编写重复的 API 调用代码
- Prompt 作为字符串变量存在于代码中，不够直观
- 流程编排受到框架约束，缺乏灵活性
- 调试和监控 LLM 调用过程困难
SimpleLLMFunc 旨在解决这些问题，使得开发者可以：
- 装饰器驱动：提供
@llm_function、@llm_chat 等装饰器，所有装饰器仅支持异步函数 (async def) 并原生适配异步调用。
- Prompt 即逻辑：Prompt 就是代码，是这个函数的逻辑实现。
- 类型安全：支持 Python 类型注解和 Pydantic 模型，确保数据结构正确。
- 多模态支持：支持文本、图片 URL 和本地图片路径的混合输入，创新性地支持工具的多模态返回。
- 通用模型接口：同时支持 OpenAI-compatible chat/completions 接口与 OpenAI Responses API 适配，易于扩展。
- API 密钥管理：智能负载均衡多个 API 密钥。
- 流量控制：集成令牌桶算法，实现智能流量平滑。
- 工具系统：支持 LLM 工具使用，具有简单易用的工具定义和调用机制，支持多模态工具返回。
- 日志完备：支持 trace_id 跟踪和搜索，方便调试和监控。
如果你关心的是“如何最快跑起来”，建议下一步直接去看 快速开始。如果你关心的是“这个框架适合我做什么”，继续阅读本页的核心特性和架构部分。 | 特性 | SimpleLLMFunc | LangChain | Dify |
|---|
| 易用性（学习曲线） | ✅ | ❌ | ✅ |
| 直观性 | ✅ | ❌ | ⭕️ |
| 灵活性 | ✅ | ✅ | ⭕️ |
| 开发速度 | ✅ | ❌ | ✅ |
| 调试性 | ✅ | ❌ | ✅ |
| 异步支持 | ✅ | ✅ | ⭕️ |
| 多模态支持 | ✅ | ⭕️ | ⭕️ |
| 流量控制 | ✅ | ⭕️ | ⭕️ |
| 类型安全 | ✅ | ⭕️ | ❌ |
| 工具集成 | ✅🌟 | ✅ | ✅ |
| 社区与生态系统 | ⭕️ | ✅ | ✅ |
样例展示
下面是一个简单的示例，展示了 SimpleLLMFunc 的基本用法：
SimpleLLMFunc 中的 @llm_function、@llm_chat、@tool 等装饰器只能装饰 async def 定义的函数，请在异步上下文中通过 await 调用。
import asyncio
from typing import List
from pydantic import BaseModel, Field
from SimpleLLMFunc import llm_function, OpenAICompatible
# 定义返回类型
class ProductAnalysis(BaseModel):
pros: List[str] = Field(..., description="产品优点")
cons: List[str] = Field(..., description="产品缺点")
rating: int = Field(..., description="评分（1-5分）")
# 配置 LLM 接口
models = OpenAICompatible.load_from_json_file("provider.json")
llm_interface = models["openai"]["gpt-3.5-turbo"]
# 创建 LLM 函数
@llm_function(llm_interface=llm_interface)
async def analyze_product(product_name: str, review: str) -> ProductAnalysis:
"""
分析产品评论，提取优缺点并给出评分。
Args:
product_name: 产品名称
review: 用户评论
Returns:
产品分析结果
"""
pass # Prompt as Code, Code as Doc
# 使用函数
async def main():
result = await analyze_product("无线耳机", "音质不错但连接不稳定")
print(f"优点: {result.pros}")
print(f"缺点: {result.cons}")
print(f"评分: {result.rating}/5")
asyncio.run(main())
OpenAIResponsesCompatible；装饰器层的写法保持不变，adapter 会把 system prompt 映射到 Responses instructions。
异步支持示例
import asyncio
from SimpleLLMFunc import llm_function
@llm_function(llm_interface=llm_interface)
async def async_translate(text: str, target_language: str) -> str:
"""
将输入文本翻译为目标语言。
Args:
text: 要翻译的文本
target_language: 目标语言
Returns:
翻译结果
"""
pass
async def main():
result = await async_translate("Hello world", "中文")
print(result)
asyncio.run(main())
多模态支持示例
import asyncio
from SimpleLLMFunc import llm_function
from SimpleLLMFunc.type import Text, ImgPath
@llm_function(llm_interface=llm_interface)
async def analyze_image(description: Text, image: ImgPath) -> str:
"""
分析图像内容
Args:
description: 分析要求描述
image: 本地图片路径
Returns:
图像分析结果
"""
pass
# 使用多模态输入
async def run():
result = await analyze_image(
description=Text("描述这张图片中的主要内容"),
image=ImgPath("./photo.jpg")
)
print(result)
asyncio.run(run())
动态模板参数示例
import asyncio
from SimpleLLMFunc import llm_function
# 万能的代码分析函数
@llm_function(llm_interface=llm_interface)
async def analyze_code(code: str) -> str:
"""以{style}的方式分析{language}代码，重点关注{focus}。"""
pass
# 万能的文本处理函数
@llm_function(llm_interface=llm_interface)
async def process_text(text: str) -> str:
"""作为{role}，请{action}以下文本，输出风格为{style}。"""
pass
async def main():
# 不同的调用方式，适应不同场景
performance_analysis = await analyze_code(
python_code,
_template_params={
'style': '详细',
'language': 'Python',
'focus': '性能优化'
}
)
code_review = await analyze_code(
js_code,
_template_params={
'style': '简洁',
'language': 'JavaScript',
'focus': '代码规范'
}
)
# 同一个函数，不同角色
edited_text = await process_text(
text,
_template_params={
'role': '专业编辑',
'action': '润色',
'style': '学术'
}
)
translated_text = await process_text(
text,
_template_params={
'role': '翻译专家',
'action': '翻译成英文',
'style': '商务'
}
)
print(performance_analysis, code_review, edited_text, translated_text)
asyncio.run(main())
核心特性
- 装饰器驱动: 使用
@llm_function、@llm_chat 构建 LLM 驱动的功能，均为原生异步实现。
- DocString 即 Prompt: 直接在函数文档中定义 Prompt，提高代码可读性。
- 动态模板参数: 支持通过
_template_params 在函数调用时动态设置 DocString 模板参数，让一个函数适应多种场景。
- 类型安全: 支持 Python 类型注解和 Pydantic 模型，确保数据结构正确。
- 异步支持:
@llm_function 与 @llm_chat 原生支持异步调用，无需额外别名。
- 多模态支持: 支持文本、图片 URL、本地图片路径的多模态输入，同时支持工具多模态返回。
- 事件流与可观测性: 通过
enable_event=True 获取完整 ReAct 事件流与 origin 元数据，便于 UI 路由与性能统计。
- SelfReference + PyRepl 运行时: 提供内置 PyRepl 与 selfref primitives，支持持久记忆、fork/spawn/wait 等自分叉能力。
- 步骤化装饰器流水线:
llm_decorator/steps 将 Prompt 构建、签名解析、ReAct 和响应解析拆分为可组合步骤。
- 基础引擎模块化:
base/messages、base/tool_call、base/type_resolve 独立演进，类型解析与多模态处理更稳健。
- 通用模型接口: 同时支持 OpenAI-compatible chat/completions 接口与 OpenAI Responses API 适配，便于扩展。
- API 密钥管理: 智能负载均衡多个 API 密钥。
- 流量控制: 集成令牌桶算法，实现智能流量平滑。
- 工具系统: 支持工具调用、参数校验、最佳实践注入与多模态返回。
- 开箱即用终端 TUI: 提供
@tui 装饰器，可将 @llm_chat Agent 包装为 Textual 终端聊天界面。
- 日志可追踪: 支持
trace_id 关联日志，便于调试与排障。
项目架构
SimpleLLMFunc 的目录结构如下：
SimpleLLMFunc/
├── __init__.py # 包初始化
├── config.py # 全局配置
├── base/ # 核心执行引擎
│ ├── messages/ # 消息构建与多模态内容生成
│ ├── tool_call/ # 工具调用参数转换、执行与校验
│ ├── type_resolve/ # 类型描述、示例与多模态类型解析
│ ├── post_process.py # 响应解析与类型转换
│ └── ReAct.py # ReAct 协调器
├── builtin/ # 内置工具
│ ├── pyrepl.py # Python REPL 工具集
│ └── self_reference.py # SelfReference 内存实现
├── hooks/ # 事件流系统
│ ├── events.py # 事件类型定义
│ ├── stream.py # 事件/响应流封装
│ ├── event_emitter.py # 工具自定义事件发射器
│ ├── event_bus.py # 事件总线
│ └── input_stream.py # 交互式输入路由
├── interface/ # LLM 接口层
│ ├── llm_interface.py # 抽象基类
│ ├── openai_compatible.py # OpenAI 兼容实现
│ ├── key_pool.py # API 密钥负载均衡
│ └── token_bucket.py # 令牌桶流量控制
├── llm_decorator/ # 装饰器与步骤化流水线
│ ├── llm_function_decorator.py
│ ├── llm_chat_decorator.py
│ ├── steps/ # Prompt/签名/执行/响应拆分
│ │ ├── common/
│ │ ├── function/
│ │ └── chat/
│ └── utils/
│ └── tools.py
├── runtime/ # 运行时原语与 worker 代理
│ ├── primitives.py
│ ├── builtin_self_reference.py
│ └── worker_proxy.py
├── self_reference.py # SelfReference 对外接口
├── utils/ # 通用工具与 TUI 组件
│ └── tui/
├── tool/ # 工具定义与序列化
│ └── tool.py
├── type/ # 类型与多模态辅助
│ ├── hooks.py
│ ├── llm.py
│ ├── message.py
│ ├── multimodal.py # Text / ImgUrl / ImgPath 等
│ └── tool_call.py
├── logger/ # 日志系统
├── observability/ # Langfuse 等集成
└── py.typed
模块介绍
LLM 接口模块
interface 模块提供与 LLM 服务通信的标准接口，支持 OpenAI-compatible 服务，并提供 OpenAI Responses API 适配。OpenAICompatible 与 OpenAIResponsesCompatible 都可通过 provider.json（提供商 -> 模型配置列表）加载多个模型实例；token_bucket.py 负责流量控制，key_pool.py 负责密钥负载均衡。
LLM 装饰器模块
llm_decorator 模块是框架的核心，提供 @llm_function 与 @llm_chat，并在 steps/ 中将 Prompt 构建、签名解析、ReAct 执行、响应解析等环节拆分为可组合步骤。多模态类型定义位于 type/multimodal.py（Text、ImgUrl、ImgPath）。
类型定义模块
type 模块导出消息、工具调用、多模态与事件流相关的类型定义，方便在签名与工具中直接使用 Text/ImgUrl/ImgPath 等类型。
日志系统
logger 模块提供结构化日志记录与 trace_id 关联，默认输出控制台日志并在 LOG_DIR/application.log 中记录 JSON 日志，便于排障和观测。
工具系统
tool 模块允许 LLM 调用外部工具和服务。工具通过 @tool 装饰器标记（仅支持 async def），并支持多模态返回（文本、图片或组合），同时可注入工具最佳实践提示。
事件系统与终端 TUI
hooks 模块提供统一事件流（LLM 调用、工具调用、自定义事件）与 origin 元数据，用于稳定路由主会话与 fork 子会话。utils/tui 基于事件流实现 @tui 装饰器，可直接把 @llm_chat Agent 包装为可交互终端界面；builtin/pyrepl.py 提供默认可用的代码执行工具集。
适用人群
SimpleLLMFunc 特别适合以下朋友：
- LLM应用开发的入门创客玩家: 学习曲线平缓，内容简单，快速上手，直观易懂。
- 快速原型开发的创业者: 需要快速验证 LLM 应用想法，缩短开发周期和迭代时间。
- 会Python的PM: 需要快速实现 LLM 应用原型，验证产品想法。
当然我们也欢迎任何一位对 LLM 应用开发感兴趣的小白，老手或者专家加入我们的社区，一起探索 LLM 应用的无限可能！