gracefox-llm-hub 0.1.1

统一的LLM调用库，支持多种LLM提供商

LLM Hub - 统一的LLM调用库

一个支持多种LLM提供商的统一调用库，提供一致的API接口、命令行工具和图形界面。

项目结构

llm-hub/
│
├── 📄 根目录配置文件
│   ├── LICENSE                          # GPL-3.0开源许可证文件
│   ├── requirements.txt                 # Python依赖包列表
│   ├── setup.py                         # 项目安装脚本，支持pip安装
│   ├── pyproject.toml                   # 项目配置，构建系统和工具配置
│   ├── MANIFEST.in                      # 打包清单，指定包含的文件
│   ├── config.json                      # 默认配置文件示例
│   ├── pytest.ini                       # pytest测试框架配置
│   ├── Makefile                         # 构建自动化脚本
│   ├── Dockerfile                       # Docker容器化配置
│   ├── .gitignore                       # Git版本控制忽略文件
│   ├── run_ui.py                        # UI界面启动脚本
│   └── README.md                        # 项目说明文档
│
├── 📁 llm_hub/                          # 核心代码目录
│   ├── __init__.py                      # 模块初始化，导出主要API
│   ├── py.typed                         # 类型标记文件，支持mypy
│   │
│   ├── 📁 cli/                          # 命令行接口模块
│   │   ├── __init__.py                  # CLI模块初始化
│   │   └── main.py                      # 命令行主程序，参数解析和交互模式
│   │
│   ├── 📁 core/                         # 核心功能模块
│   │   ├── __init__.py                  # 核心模块初始化
│   │   ├── client.py                    # LLMClient主类，统一API调用接口
│   │   ├── config.py                    # 配置管理，加载/保存配置
│   │   └── enums.py                     # 枚举定义（Provider, ModelType等）
│   │
│   ├── 📁 models/                       # 数据模型模块
│   │   ├── __init__.py                  # 模型模块初始化
│   │   ├── message.py                   # 消息和对话模型（Message, Conversation）
│   │   └── response.py                  # 响应模型（Response, StreamResponse）
│   │
│   ├── 📁 providers/                    # LLM提供商实现模块
│   │   ├── __init__.py                  # 提供商模块初始化，工厂方法
│   │   ├── base.py                      # 提供商基类，定义统一接口
│   │   ├── openai_compatible.py         # OpenAI兼容提供商（通用）
│   │   ├── ollama.py                    # Ollama本地部署提供商
│   │   ├── llama_cpp.py                 # llama.cpp本地模型提供商
│   │   ├── deepseek.py                  # DeepSeek API提供商
│   │   ├── kimi.py                      # Kimi API提供商
│   │   ├── gemini.py                    # Google Gemini API提供商
│   │   ├── anthropic.py                 # Anthropic Claude API提供商
│   │   └── custom.py                    # 自定义API提供商
│   │
│   └── 📁 utils/                        # 工具函数模块
│       ├── __init__.py                  # 工具模块初始化
│       ├── logger.py                    # 日志系统，文件和控制台输出
│       ├── token_counter.py             # Token计数器，估算API使用量
│       └── helpers.py                   # 辅助函数（时间格式化、重试等）
│
├── 📁 ui/                               # 图形界面模块
│   ├── __init__.py                      # UI模块初始化
│   └── app.py                           # 主UI应用，Tkinter图形界面
│
├── 📁 tests/                            # 测试模块
│   ├── __init__.py                      # 测试模块初始化
│   ├── test_client.py                   # 客户端功能测试
│   └── test_providers.py                # 各提供商功能测试
│
└── 📁 examples/                         # 示例代码目录
    ├── basic_usage.py                   # 基础使用示例（单轮/多轮对话）
    ├── streaming.py                     # 流式输出示例
    ├── multi_turn_chat.py               # 多轮对话示例（带历史记录）
    └── environment_aware.py             # 环境感知示例（结合系统信息）

文件功能详解

根目录文件

文件	作用	使用场景
LICENSE	GPL-3.0许可证	开源许可声明
requirements.txt	Python依赖列表	安装依赖：pip install -r requirements.txt
setup.py	安装脚本	项目安装：pip install -e .
pyproject.toml	项目配置	构建系统和工具配置（black, pytest, mypy）
MANIFEST.in	打包清单	指定打包时包含的文件
config.json	默认配置	存储LLM配置（API密钥、模型参数等）
pytest.ini	测试配置	pytest框架配置
Makefile	构建自动化	运行命令：make install, make test, make clean
Dockerfile	Docker配置	容器化部署：docker build -t llm-hub .
.gitignore	Git忽略	排除临时文件、缓存等
run_ui.py	UI启动脚本	启动图形界面：python run_ui.py
README.md	项目说明	文档和快速开始指南

核心模块 (llm_hub/)

文件	类/函数	作用
__init__.py	LLMClient, LLMConfig, Provider	导出主要API
cli/main.py	main(), interactive_mode()	命令行参数解析，交互式对话
core/client.py	LLMClient	统一客户端，chat/complete/stream方法
core/config.py	LLMConfig	配置管理，load/save方法
core/enums.py	Provider, ModelType	提供商和模型类型枚举
models/message.py	Message, Conversation	消息和对话数据结构
models/response.py	Response, StreamResponse	响应数据结构
providers/base.py	BaseProvider	提供商基类，定义接口规范
providers/openai_compatible.py	OpenAICompatibleProvider	OpenAI格式API支持
providers/ollama.py	OllamaProvider	Ollama本地服务支持
providers/llama_cpp.py	LlamaCppProvider	llama.cpp本地模型支持
providers/deepseek.py	DeepSeekProvider	DeepSeek API支持
providers/kimi.py	KimiProvider	Kimi API支持
providers/gemini.py	GeminiProvider	Google Gemini支持
providers/anthropic.py	AnthropicProvider	Claude API支持
providers/custom.py	CustomProvider	自定义API支持
utils/logger.py	setup_logger(), get_logger()	日志系统，支持文件和控制台
utils/token_counter.py	TokenCounter	Token计数，估算使用量
utils/helpers.py	retry_on_failure(), truncate_text()	辅助函数

UI模块 (ui/)

文件	类	作用
app.py	LLMHubUI	Tkinter图形界面，提供商切换、对话、配置

测试模块 (tests/)

文件	测试内容
test_client.py	客户端API测试（chat, complete, stream）
test_providers.py	各提供商功能测试

示例模块 (examples/)

文件	演示内容
basic_usage.py	基础API使用、配置加载
streaming.py	流式输出、回调处理
multi_turn_chat.py	多轮对话、历史管理
environment_aware.py	结合系统信息的智能对话

快速开始

安装

# 基础安装
pip install -e .

# 安装所有依赖（包括UI）
pip install -e .[all]

# 仅安装UI依赖
pip install -e .[ui]

作为库使用

from llm_hub import LLMClient, LLMConfig, Provider

# 创建客户端
client = LLMClient(LLMConfig(
    provider=Provider.DEEPSEEK,
    model="deepseek-chat",
    api_key="your-api-key"
))

# 对话
response = client.chat("你好")
print(response.content)

# 流式输出
for chunk in client.stream_chat("讲个故事"):
    print(chunk, end="")

命令行使用

# 基本使用
llm-hub --provider deepseek --api-key YOUR_KEY "你好"

# 交互模式
llm-hub --provider ollama --interactive

# 使用配置文件
llm-hub --config config.json --interactive

# 流式输出
llm-hub --provider openai --stream "讲个故事"

图形界面

# 启动UI
python run_ui.py
# 或
llm-hub-ui

支持的提供商

提供商	类型	需要API Key	配置参数
OpenAI	云端	✓	api_key
DeepSeek	云端	✓	api_key
Kimi	云端	✓	api_key
Google Gemini	云端	✓	api_key
Anthropic Claude	云端	✓	api_key
Ollama	本地	✗	ollama_url
llama.cpp	本地	✗	model_path
自定义	可选	可选	api_url

开发命令

# 安装开发依赖
make install-dev

# 运行测试
make test

# 代码格式化
make format

# 代码检查
make lint

# 清理临时文件
make clean

# 构建发布包
make build

# 运行命令行
make run-cli

# 运行UI
make run-ui

依赖关系

cli/main.py ──→ core/client.py ──→ providers/__init__.py ──→ providers/base.py
                    ↓                      ↓                        ↓
ui/app.py ─────→ core/config.py    providers/ollama.py      models/message.py
                    ↓                      ↓                        ↓
                core/enums.py       providers/llama_cpp.py   models/response.py
                    ↓                      ↓
                utils/logger.py     providers/openai_compatible.py
                    ↓                      ↓
                utils/token_counter.py    providers/deepseek.py
                                          providers/kimi.py
                                          providers/gemini.py
                                          providers/anthropic.py
                                          providers/custom.py

扩展开发

添加新提供商

1. 在 core/enums.py 添加枚举：

class Provider(Enum):
    NEW_PROVIDER = "new_provider"

2. 创建 providers/new_provider.py：

from llm_hub.providers.base import BaseProvider

class NewProvider(BaseProvider):
    def chat(self, conversation, **kwargs):
        # 实现对话逻辑
        pass

3. 在 providers/__init__.py 注册：

from llm_hub.providers.new_provider import NewProvider

providers = {
    Provider.NEW_PROVIDER: NewProvider,
    # ...
}

许可证

GNU General Public License v3.0 - 详见 LICENSE 文件

GPL-3.0 核心要求

• 自由使用：任何人都可以自由使用本软件
• 源代码公开：分发软件时必须提供源代码
• 相同许可证：修改后的版本必须在相同的GPL-3.0许可证下发布
• 版权声明：必须保留原始版权和许可证声明

详见：https://www.gnu.org/licenses/gpl-3.0.html