快速开始
欢迎使用 SimpleLLMFunc！本指南将帮助您从零开始，快速搭建并运行您的第一个 LLM 应用。
环境要求
Python 3.12 或更高版本
支持的操作系统：Windows、macOS、Linux
第一步：环境准备
1.1 创建虚拟环境
推荐使用虚拟环境来管理项目依赖：
# 使用 venv 创建虚拟环境
python -m venv simplellmfunc_env
# 激活虚拟环境
# Windows
simplellmfunc_env\Scripts\activate
# macOS/Linux
source simplellmfunc_env/bin/activate
1.2 安装 SimpleLLMFunc
有两种安装方式：
方式一：从 PyPI 安装（推荐）
pip install SimpleLLMFunc
方式二：从源码安装
# 克隆项目
git clone https://github.com/NiJingzhe/SimpleLLMFunc.git
cd SimpleLLMFunc
# 使用 Poetry 安装依赖
poetry install
# 或者使用 pip 安装
pip install -e .
第二步：配置 API 密钥
2.1 创建配置文件
在项目根目录创建 .env 文件：
# 复制环境模板
cp env_template .env
编辑 .env 文件，配置日志设置（可选）：
# 日志级别（默认 DEBUG）
LOG_LEVEL=INFO
# 日志目录（默认 logs）
LOG_DIR=logs
2.2 创建模型配置文件
创建 provider.json 文件来配置您的 LLM 模型：
{
"openai": [
{
"model_name": "gpt-3.5-turbo",
"api_keys": ["sk-test-key-1", "sk-test-key-2"],
"base_url": "https://api.openai.com/v1",
"max_retries": 5,
"retry_delay": 1.0,
"rate_limit_capacity": 20,
"rate_limit_refill_rate": 3.0
},
{
"model_name": "gpt-4",
"api_keys": ["sk-test-key-3"],
"base_url": "https://api.openai.com/v1",
"max_retries": 5,
"retry_delay": 1.0,
"rate_limit_capacity": 10,
"rate_limit_refill_rate": 1.0
}
],
"zhipu": [
{
"model_name": "glm-4",
"api_keys": ["zhipu-test-key-1", "zhipu-test-key-2"],
"base_url": "https://open.bigmodel.cn/api/paas/v4/",
"max_retries": 3,
"retry_delay": 0.5,
"rate_limit_capacity": 15,
"rate_limit_refill_rate": 2.0
}
]
}
重要提示：
provider.json采用 提供商 -> 模型配置列表 的结构model_name会作为models[provider][model_name]的索引键支持多个 API 密钥，系统会自动进行负载均衡
可以配置多个不同的模型提供商
第三步：创建第一个 Demo
3.1 基础文本分析示例
创建一个名为 first_demo.py 的文件：
⚠️ SimpleLLMFunc 中的所有装饰器（如
@llm_function、@llm_chat、@tool）都要求装饰async def定义的函数；使用时请在异步上下文中通过await调用，或使用asyncio.run启动顶层任务。
import asyncio
from typing import List
from pydantic import BaseModel, Field
from SimpleLLMFunc import llm_function, OpenAICompatible
# 定义返回类型
class TextAnalysis(BaseModel):
sentiment: str = Field(..., description="情感分析结果：积极、消极或中性")
keywords: List[str] = Field(..., description="提取的关键词列表")
summary: str = Field(..., description="文本摘要")
# 加载模型接口（从 provider.json 配置文件）
models = OpenAICompatible.load_from_json_file("provider.json")
gpt_interface = models["openai"]["gpt-3.5-turbo"]
# 创建 LLM 函数
@llm_function(llm_interface=gpt_interface)
async def analyze_text(text: str) -> TextAnalysis:
"""分析给定文本的情感、关键词和摘要
Args:
text: 需要分析的文本内容
Returns:
包含情感分析、关键词和摘要的结构化结果
"""
pass
async def main():
# 测试文本
test_text = """
今天天气非常好，阳光明媚，温度适宜。我决定去公园散步，
看到很多人在户外活动，孩子们在玩耍，老人们在下棋。
整个公园充满了生机和活力，让人心情愉悦。
"""
print("=== 文本分析 Demo ===")
print(f"输入文本: {test_text.strip()}")
print("\n分析结果:")
try:
result = await analyze_text(test_text)
print(f"情感: {result.sentiment}")
print(f"关键词: {', '.join(result.keywords)}")
print(f"摘要: {result.summary}")
except Exception as e:
print(f"分析失败: {e}")
if __name__ == "__main__":
asyncio.run(main())
3.2 运行 Demo
python first_demo.py
您应该看到类似以下的输出：
=== 文本分析 Demo ===
输入文本: 今天天气非常好，阳光明媚，温度适宜。我决定去公园散步，看到很多人在户外活动，孩子们在玩耍，老人们在下棋。整个公园充满了生机和活力，让人心情愉悦。
分析结果:
情感: 积极
关键词: 天气, 阳光, 公园, 散步, 户外活动, 生机, 活力
摘要: 描述了一个阳光明媚的日子，作者在公园散步时看到各种户外活动，感受到生机和活力，心情愉悦。
第四步：进阶示例
4.1 动态模板参数示例
这个示例展示了如何使用 _template_params 让同一个函数适应不同的使用场景：
import asyncio
from SimpleLLMFunc import llm_function, OpenAICompatible
# 加载模型接口
models = OpenAICompatible.load_from_json_file("provider.json")
gpt_interface = models["openai"]["gpt-3.5-turbo"]
# 万能的代码分析函数
@llm_function(llm_interface=gpt_interface)
async def analyze_code(code: str) -> str:
"""以{style}的方式分析{language}代码，重点关注{focus}。"""
pass
# 万能的文本处理函数
@llm_function(llm_interface=gpt_interface)
async def process_text(text: str) -> str:
"""作为{role}，请{action}以下文本，输出风格为{style}。"""
pass
async def main():
print("=== 动态模板参数 Demo ===")
# 测试代码
python_code = """
def fibonacci(n):
if n <= 1:
return n
return fibonacci(n-1) + fibonacci(n-2)
"""
# 不同的分析方式
print("\n1. 代码分析 - 性能优化:")
try:
performance_result = await analyze_code(
python_code,
_template_params={
'style': '详细',
'language': 'Python',
'focus': '性能优化'
}
)
print(performance_result)
except Exception as e:
print(f"分析失败: {e}")
print("\n2. 代码分析 - 代码规范:")
try:
style_result = await analyze_code(
python_code,
_template_params={
'style': '简洁',
'language': 'Python',
'focus': '代码规范'
}
)
print(style_result)
except Exception as e:
print(f"分析失败: {e}")
# 不同的文本处理角色
sample_text = "人工智能技术正在快速发展，对各行各业产生深远影响。"
print("\n3. 文本处理 - 编辑润色:")
try:
edited_result = await process_text(
sample_text,
_template_params={
'role': '专业编辑',
'action': '润色',
'style': '学术'
}
)
print(edited_result)
except Exception as e:
print(f"处理失败: {e}")
print("\n4. 文本处理 - 翻译转换:")
try:
translated_result = await process_text(
sample_text,
_template_params={
'role': '翻译专家',
'action': '翻译成英文',
'style': '商务'
}
)
print(translated_result)
except Exception as e:
print(f"处理失败: {e}")
if __name__ == "__main__":
asyncio.run(main())
这个示例展示了动态模板参数的核心优势：
一个函数定义，多种使用场景
调用时动态指定角色和任务
代码复用性大大提高
4.2 带工具调用的示例
创建一个更复杂的示例，展示工具调用功能：
import asyncio
from typing import Dict, List
from pydantic import BaseModel, Field
from SimpleLLMFunc import llm_function, tool, OpenAICompatible
# 加载模型接口
models = OpenAICompatible.load_from_json_file("provider.json")
gpt_interface = models["openai"]["gpt-3.5-turbo"]
# 定义工具
@tool(name="get_weather", description="获取指定城市的天气信息")
async def get_weather(city: str) -> Dict[str, str]:
"""获取指定城市的天气信息
Args:
city: 城市名称
Returns:
包含温度、湿度和天气状况的字典
"""
# 模拟天气数据
weather_data = {
"北京": {"temperature": "25°C", "humidity": "60%", "condition": "晴朗"},
"上海": {"temperature": "28°C", "humidity": "75%", "condition": "多云"},
"广州": {"temperature": "30°C", "humidity": "80%", "condition": "小雨"}
}
return weather_data.get(city, {"temperature": "20°C", "humidity": "50%", "condition": "未知"})
# 定义返回类型
class TravelRecommendation(BaseModel):
city: str = Field(..., description="推荐的城市")
weather_info: Dict[str, str] = Field(..., description="天气信息")
activities: List[str] = Field(..., description="推荐的活动")
reason: str = Field(..., description="推荐理由")
# 创建带工具调用的 LLM 函数
@llm_function(llm_interface=gpt_interface, toolkit=[get_weather])
async def recommend_travel(preference: str) -> TravelRecommendation:
"""根据用户偏好推荐旅游目的地和活动
Args:
preference: 用户的旅游偏好描述
Returns:
包含推荐城市、天气信息、活动和理由的结构化结果
"""
pass
async def main():
preference = "我喜欢温暖的气候，想要进行户外活动，最好是能看到美丽的风景"
print("=== 旅游推荐 Demo ===")
print(f"用户偏好: {preference}")
print("\n推荐结果:")
try:
result = await recommend_travel(preference)
print(f"推荐城市: {result.city}")
print(f"天气信息: {result.weather_info}")
print(f"推荐活动: {', '.join(result.activities)}")
print(f"推荐理由: {result.reason}")
except Exception as e:
print(f"推荐失败: {e}")
if __name__ == "__main__":
asyncio.run(main())
第五步：查看日志
SimpleLLMFunc 提供了内建日志系统。运行 Demo 后，您可以：
查看控制台输出日志（含 trace_id）
检查
LOG_DIR/application.log的结构化日志（默认logs/application.log）若启用 PyRepl，查看
LOG_DIR/pyrepl/<instance_id>/executions.jsonl的执行审计
每个函数调用都会生成唯一的 trace_id，便于追踪和调试。
常见问题
Q: API 密钥配置错误怎么办？
A: 请检查 provider.json 文件中的 API 密钥是否正确，确保密钥有效且有足够的配额。
Q: 模型返回格式不正确怎么办？
A: 对于复杂返回类型，框架会要求模型输出 XML 结构。若模型经常输出不合规 XML，建议切换更强模型或在 DocString 中强化格式约束。
Q: 如何添加更多工具？
A: 使用 @tool 装饰器定义工具函数，然后在 @llm_function 的 toolkit 参数中传入工具列表。
Q: 如何实现异步调用？
A: SimpleLLMFunc 中的装饰器（如 @llm_function、@llm_chat、@tool）只支持 async def 定义的函数，因此需要在异步上下文中通过 await 调用，或在脚本入口使用 asyncio.run。
Q: 什么是动态模板参数？
A: 动态模板参数允许您在函数调用时通过 _template_params 参数动态设置 DocString 中的占位符，让同一个函数适应不同的使用场景。
Q: 如何使用动态模板参数？
A: 在 DocString 中使用 {变量名} 占位符，调用时通过 _template_params 传入变量值。例如：
@llm_function(llm_interface=llm)
async def analyze_code(code: str) -> str:
"""以{style}的方式分析{language}代码，重点关注{focus}。"""
pass
import asyncio
async def main():
result = await analyze_code(code, _template_params={
'style': '详细', 'language': 'Python', 'focus': '性能优化'
})
print(result)
asyncio.run(main())
下一步
恭喜！您已经成功运行了第一个 SimpleLLMFunc 应用。接下来您可以：
探索更多示例代码（在
examples/目录中）阅读详细文档了解高级功能
尝试创建自己的 LLM 应用
参与社区讨论和贡献
祝您使用愉快！