llmakits
用于简化大语言模型(LLM)的集成和管理。支持多模型调度、故障转移、负载均衡等功能。
支持通过YAML配置实现不同业务场景的模型组管理，日均承载数万次LLM调用（含多模态图文请求），将多模型运维复杂度降低约70%。
功能特性
- 🚀 多模型支持: 支持OpenAI、智谱AI、DashScope、ModelScope等多个主流LLM平台；
- 🔄 智能调度: 内置多层故障转移和负载均衡机制；
- 自动切换：当模型失败时，自动切换到下个可用模型；
- 负载均衡：Token 或 请求次数 达到上限后，自动切换到下个api_key；
- 密钥检测：自动检测并移除API密钥用尽的模型；
- 图片处理：支持图片URL自动转base64、多图批量处理、失败域名智能降级（自动转为单图重试）、LRU缓存避免重复下载；
- 📊 消息处理: 强大的消息格式化、结果验证和提取功能；
- 🛡️ 错误处理: 完善的LLM重试机制和异常处理；
- 🎯 电商工具: 内置电商场景专用工具集，提供带验证器的闭环工作流；
- 📝 流式输出: 支持流式响应，自动转静态处理；
- 💡 状态保持: 模型实例缓存，避免重复实例化，保持API密钥切换状态。
- ⏱️ 性能监控: 支持设置耗时警告阈值，监控模型响应性能，并输出响应报告；
安装/更新
pip install --upgrade llmakits
快速开始
1. 配置模型和API密钥
配置文件支持三种数据结构：文件路径（str）、配置字典（dict）、pandas DataFrame（仅密钥配置和全局配置）。完整字段结构请参考 docs/configs/ 目录下的配置文档：
模型配置文件 (config/models_config.yaml):
- 支持按业务场景分组配置
- 每个组可以配置多个模型，实现故障转移
- 模型会按配置顺序依次尝试，直到成功
# 标题生成专用模型组
generate_title:
- sdk_name: "dashscope"
model_name: "qwen3-max-preview"
- sdk_name: "zhipu"
model_name: "glm-4-plus"
# 翻译专用模型组
translate_box:
- sdk_name: "modelscope"
model_name: "Qwen/Qwen3-32B"
- sdk_name: "modelscope"
model_name: "deepseek-ai/DeepSeek-V3"
字段结构详情（支持 str/dict）请参考 docs/configs/models_config.md。
密钥配置文件 (config/keys_config.yaml):
- 支持多密钥配置，自动负载均衡
- 当密钥达到每日使用限制时，自动切换到下一个密钥
- 支持不同平台的独立配置
# 阿里云DashScope平台
dashscope:
base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
api_keys: ["your-api-key-1", "your-api-key-2"]
# ModelScope平台
modelscope:
base_url: "https://api-inference.modelscope.cn/v1/"
api_keys: ["your-api-key-1", "your-api-key-2"]
字段结构详情（支持 str/dict/pandas DataFrame）请参考 docs/configs/keys_config.md。
错误处理和故障转移
- 模型级别故障转移: 当前模型失败时，自动切换到同组的下一个模型
- API密钥用尽检测: 自动检测
API_KEY_EXHAUSTED异常，并移除对应的模型 - 结果验证: 支持自定义验证函数，验证失败时自动尝试下一个模型
- 状态保持: 模型实例在dispatcher中缓存，保持API密钥切换状态
配置优化建议
- 使用模型组: 推荐使用
execute_with_group方法，避免重复实例化 - 合理配置模型顺序: 将性能更好、更稳定的模型放在前面
- 适当设置重试: 根据业务需求配置模型数量和密钥数量
- 监控切换次数: 通过
model_switch_count监控模型切换频率
全局模型配置
支持通过CSV/XLSX文件或pandas DataFrame配置模型的高级参数（流式输出、思考模式等）。
详见 docs/configs/global_model_config.md。
2. 加载模型
from llmakits import load_models
# 方式1：传入配置文件路径（字符串）
models, keys = load_models('config/models_config.yaml', 'config/keys_config.yaml')
# 方式2：直接传入配置字典
models_config = {
"my_models": [
{"model_name": "gpt-3.5-turbo", "sdk_name": "openai"}
]
}
model_keys = {
"openai": {
"base_url": "https://api.openai.com/v1",
"api_keys": ["your-api-key"]
}
}
models, keys = load_models(models_config, model_keys)
# 方式3：使用全局配置（支持高级参数配置）
models, keys = load_models(
'config/models_config.yaml',
'config/keys_config.yaml',
global_config='config/global_model_config.csv' # 可选：全局模型配置
)
# 方式4：传入pandas DataFrame（密钥配置和全局配置支持DataFrame）
import pandas as pd
keys_df = pd.DataFrame({
"platform": ["openai"],
"base_url": ["https://api.openai.com/v1"],
"api_keys": [["your-api-key-1", "your-api-key-2"]] # 也支持分隔符字符串"key-1;key-2"；或改用api_key单列（每行一个密钥，同平台多行自动聚合）
})
global_config_df = pd.read_csv('config/global_model_config.csv')
models, keys = load_models('config/models_config.yaml', keys_df, global_config=global_config_df)
# 获取模型组
my_models = models['my_models']
3. 加载提示词
使用 PromptManager 管理提示词模板，支持从指定文件夹批量加载 .md 格式的提示词文件。
from llmakits import PromptManager
# 初始化（加载基础提示词 + 指定子文件夹）
prompt_manager = PromptManager('prompts', subfolder_name='e_commerce')
# 获取提示词
title_prompt = prompt_manager.get_prompt('generate_title')
# 在业务中使用
message_info = {
"system_prompt": title_prompt,
"user_text": "请为这款无线蓝牙耳机生成标题"
}
详细使用说明请参考 docs/prompt_manager.md。
4. 发送消息（多模型调度）
使用 ModelDispatcher（推荐）
ModelDispatcher 提供了两种使用方式，推荐使用 execute_with_group 方法：
方式一：使用模型组（execute_with_group）
from llmakits import ModelDispatcher
# 创建调度器实例并加载配置
dispatcher = ModelDispatcher('config/models_config.yaml', 'config/keys_config.yaml')
# 准备消息
message_info = {
"system_prompt": "你是一个 helpful 助手",
"user_text": "请介绍一下Python编程语言"
}
# 使用模型组执行任务 - 自动管理模型状态和故障转移
result, tokens = dispatcher.execute_with_group(message_info, group_name="generate_title")
print(f"结果: {result}")
print(f"使用token数: {tokens}")
print(f"模型切换次数: {dispatcher.model_switch_count}")
消息格式说明
message_info 参数支持以下字段：
system_prompt: 系统提示词（可选）user_text: 用户输入文本（可选）include_img: 是否包含图片（可选，默认False）img_list: 图片URL列表（可选，默认为空列表）debug: 是否启用调试模式（可选，默认False），启用后异常时会触发断点
基本使用示例：
# 简单文本对话
message_info = {
"system_prompt": "你是一个 helpful 助手",
"user_text": "请介绍一下Python编程语言"
}
# 带图片的对话
message_info = {
"system_prompt": "你是一个图像分析专家",
"user_text": "请分析这张图片",
"include_img": True,
"img_list": ["https://example.com/image.jpg"]
}
# 如果include_img = True 同时 img_list 是空的，此时会报出错误。
方式二：手动传入模型列表（execute_task）
from llmakits import ModelDispatcher
# 创建调度器实例
dispatcher = ModelDispatcher()
# 准备消息和模型列表
message_info = {
"system_prompt": "你是一个 helpful 助手",
"user_text": "请介绍一下Python编程语言"
}
# 执行任务
result, tokens = dispatcher.execute_task(message_info, my_models)
高级用法
增强版调度策略：dispatcher_with_repair
from llmakits import dispatcher_with_repair
# 创建调度器
from llmakits import ModelDispatcher
dispatcher = ModelDispatcher('config/models_config.yaml', 'config/keys_config.yaml')
# 准备消息
message_info = {
"system_prompt": "你是一个JSON数据生成专家",
"user_text": "请生成一个包含产品信息的JSON对象"
}
# 使用增强版调度策略 - 自动修复JSON错误
try:
result, tokens = dispatcher_with_repair(
dispatcher=dispatcher,
message_info=message_info,
group_name="generate_json", # 主模型组名称
validate_func=None, # 可选：自定义验证函数
fix_json_config={
"group_name": "fix_json", # 修复模型组名称
"system_prompt": "你是一个JSON修复专家，请修复下面错误的JSON格式",
"example_json": '{"name": "产品名称", "price": 99.99}' # 可选：JSON示例
}
)
print(f"修复后的结果: {result}")
print(f"使用token数: {tokens}")
except Exception as e:
print(f"所有模型和修复尝试均失败: {e}")
增强版调度策略特点：
- 自动修复JSON错误：当主模型返回格式错误的JSON时，自动调用修复模型组进行修复
- 多模型支持：每个失败的模型都会尝试修复，确保所有主模型都有机会尝试
- 独立修复流程：使用独立的修复调度器，避免状态混乱
- 详细错误处理：区分JSON错误和其他类型错误，采取不同的处理策略
使用场景：
- 需要生成结构化JSON数据的任务
- 对JSON格式要求严格的场景
- 希望提高任务成功率的自动化流程
4. 直接使用模型客户端
from llmakits import BaseOpenai
# 创建模型客户端
model = BaseOpenai(
platform="openai",
base_url="https://api.openai.com/v1",
api_keys=["your-api-key"],
model_name="gpt-3.5-turbo"
)
# 方法1: 使用消息列表格式（兼容OpenAI格式）
messages = [
{"role": "system", "content": "你是一个 helpful 助手"},
{"role": "user", "content": "Hello!"}
]
result, tokens = model.send_message(messages)
print(f"回复: {result}")
# 方法2: 使用message_info格式（推荐）
message_info = {
"system_prompt": "你是一个 helpful 助手",
"user_text": "Hello!"
}
result, tokens = model.send_message([], message_info)
print(f"回复: {result}")
高级配置选项
from llmakits import BaseOpenai
# 创建带高级配置的客户端
client = BaseOpenai(
platform="openai",
base_url="https://api.openai.com/v1",
api_keys=["your-api-key"],
model_name="gpt-4o",
stream=True, # 启用流式输出
stream_real=False, # 真实流式输出
request_timeout=60, # 请求超时时间（秒）
max_retries=3 # 最大重试次数
)
获取模型信息
# 获取模型列表（DataFrame格式，包含创建时间等信息）
models_df = client.models_df()
print(f"模型列表:")
print(models_df)
高级功能
JSON字符串转换，字段提取
from llmakits.message import extract_field, convert_to_json
# 提取并转换为JSON
json_str = '{"name": "test"} some text'
result = convert_to_json(json_str)
# 提取字段
field_value = extract_field(json_str, "name")
print(field_value) # 输出: test
# 提取多个字段
name, age = extract_field(json_str, "name", "age")
print(name) # 输出: test
print(age) # 输出: None
电商工具
| 功能 | 说明 |
|---|---|
| 基础工具函数 | 中文字符检测、字符长度检测、HTML 验证 |
| 优化商品标题 | 支持长度/单词数约束检查，不合格自动修改 |
| 预测商品类目 | 直接预测，支持 JSON 修复 |
| 梯度预测商品类目 | 逐级预测，支持 JSON 修复 |
| 翻译商品选项 | 多语言翻译，自动验证返回列表长度一致性 |
| 生成 HTML 商品描述 | 自动生成 HTML，自动检测并修复非法标签 |
| 填充属性值 | 从候选值中自动验证并填充商品属性 |
许可证
Apache 2.0 License
1 maintainer
Metadata
1 maintainer
Release files for llmakits 0.6.71
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| llmakits-0.6.71.tar.gz | 60.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| llmakits-0.6.71-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 125.7 kB
Release files / llmakits-0.6.71.tar.gz
| Download URL | llmakits-0.6.71.tar.gz |
|---|---|
| Size | 60.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
18c6a17237d49b622c70dc5c74e29434d35c36d0c7da03b3b72db81372c8cdfc
|
|
BLAKE2b-256 checksum How to use checksums |
59ca37b7e6b570ffb248d8e5e76926c80ee8938ef29e218e8fc4296fdc24f15f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
Release files / llmakits-0.6.71-py3-none-any.whl
| Download URL | llmakits-0.6.71-py3-none-any.whl |
|---|---|
| Size | 65.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b3a5c19e4b2424c3efc1febab2af5df05c34531b1834761ea8c4f372e066f7e9
|
|
BLAKE2b-256 checksum How to use checksums |
425c520a0c65b9bac38c7e9a503f1dfbba5f923a72259f4c7a0c069ac6301260
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.7
|
