# padwan-llm：轻量级多提供商统一的LLM客户端

> 介绍padwan-llm项目，一个基于niquests构建的极简Python LLM客户端，支持OpenAI、Gemini、Mistral、Grok等多个提供商，内置MCP工具支持和推理模型流式输出。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-02T14:13:52.000Z
- 最近活动: 2026-05-02T14:23:35.222Z
- 热度: 163.8
- 关键词: LLM, OpenAI, Gemini, Mistral, Grok, Python, 异步, MCP, Agent, niquests
- 页面链接: https://www.zingnex.cn/forum/thread/padwan-llm-llm-cdb0ca45
- Canonical: https://www.zingnex.cn/forum/thread/padwan-llm-llm-cdb0ca45
- Markdown 来源: ingested_event

---

# padwan-llm：轻量级多提供商统一的LLM客户端

## 背景：LLM客户端的碎片化困境

随着大语言模型（LLM）生态的蓬勃发展，开发者在实际项目中常常面临一个尴尬的局面：不同的模型提供商有着各自独立的SDK和API规范。OpenAI有openai库，Google Gemini有google-genai，Mistral和Grok也各有其道。这种碎片化带来了几个问题：

首先，代码的可移植性受到严重限制。一个为OpenAI编写的应用，如果要切换到Gemini，往往需要重写大量调用代码。其次，依赖管理变得复杂，每个SDK都可能引入自己的依赖树，增加项目的体积和潜在冲突。最后，学习成本也随之上升，开发者需要熟悉多套不同的API设计风格。

padwan-llm项目正是为了解决这些痛点而生。它提供了一个统一的、极简的Python客户端，让开发者可以用一致的接口与多个LLM提供商交互，同时保持轻量级的依赖 footprint。

## 项目核心理念

padwan-llm的设计哲学可以概括为三个关键词：极简、统一、现代。

**极简**：项目只有一个运行时依赖——niquests。这是一个现代化的Python HTTP客户端，支持HTTP/2和HTTP/3协议协商，相比传统的requests库更加高效。

**统一**：无论底层是OpenAI、Gemini、Mistral还是Grok，开发者使用相同的API模式进行调用。这种抽象层屏蔽了底层差异，让代码更加可维护。

**现代**：项目充分利用了Python的异步特性（async/await），所有主要接口都支持异步调用，适合构建高性能的并发应用。同时，它也原生支持流式输出、工具调用、MCP协议等前沿特性。

## 核心功能详解

### 1. 多提供商支持

padwan-llm内置支持主流的LLM提供商：

- **OpenAI**：包括GPT-4、GPT-4o、GPT-4o-mini等全系列模型
- **Google Gemini**：支持Gemini Pro、Flash等模型
- **Mistral AI**：支持Mistral系列模型
- **Grok**：xAI的Grok模型
- **OpenAI兼容API**：通过OpenAIClient配合自定义base_url，可以支持Groq、Together AI、Ollama、vLLM等任何兼容OpenAI API格式的服务

提供商的识别是自动的，基于模型名称的前缀或环境变量中的API密钥。例如，以"gpt-"开头的模型会自动路由到OpenAI，以"gemini-"开头的会路由到Gemini。

### 2. 异步优先设计

所有核心操作都支持异步模式，这对于构建高并发的AI应用至关重要：

```python
async with LLMClient(model="gpt-4o") as client:
    response, usage = await client.complete_chat(
        [{"role": "user", "content": "Hello!"}]
    )
```

使用`async with`上下文管理器确保资源的正确释放，同时支持连接池复用，提升性能。

### 3. 流式输出支持

对于长文本生成场景，流式输出可以显著提升用户体验。padwan-llm提供了简洁的流式API：

```python
stream = client.stream_chat(state.messages)
async for text in stream:
    print(text, end="", flush=True)
```

流对象还会携带使用量信息（usage），方便进行成本统计和配额管理。

### 4. 对话状态管理

项目提供了ConversationState类来管理多轮对话的上下文：

```python
state = ConversationState(system="你是一个简洁的助手。")
state.add_user_message("Python是什么？")
# 生成回复后
state.add_assistant_message(response_text)
```

这种设计使得维护对话历史变得简单直观，同时支持系统提示词（system prompt）的设置。

### 5. AgentSession：智能代理会话

这是padwan-llm的一个亮点功能。AgentSession类实现了一个完整的ReAct（Reasoning + Acting）代理循环：

```python
async with AgentSession(
    client=LLMClient(model="gpt-4o"),
    mcp_tools=[McpStdio(command="uvx", args=["my-mcp-server"])],
    system="你可以使用工具。在有帮助时使用它们。",
) as session:
    async for chunk in session.stream("巴黎的天气怎么样？"):
        print(chunk, end="", flush=True)
```

AgentSession的工作流程如下：

1. 接收用户输入
2. 调用LLM判断是否需要使用工具
3. 如果需要，执行工具调用并获取结果
4. 将工具结果反馈给LLM
5. 重复步骤2-4直到LLM给出最终文本回复
6. 返回最终答案

这种模式支持顺序或并行的工具执行，还可以通过钩子函数实现工具调用的审批机制，以及自定义的错误处理逻辑。

### 6. MCP协议支持

Model Context Protocol（MCP）是Anthropic推出的开放协议，旨在标准化AI模型与外部工具、数据源之间的交互。padwan-llm原生支持MCP，提供了两种传输方式：

**Streamable HTTP传输**：用于连接远程MCP服务器

```python
async with McpStreamable(url="https://mcp.example.com/mcp", token="sk-...") as mcp:
    for tool in mcp.tools:
        print(tool.name, tool.description)
```

**Stdio传输**：用于启动本地子进程作为MCP服务器

```python
async with McpStdio(command="uvx", args=["my-mcp-server"]) as mcp:
    result = await mcp.tools[0].handler({"query": "hello"})
```

这种设计让padwan-llm可以轻松接入任何符合MCP规范的工具生态，大大扩展了应用的可能性。

### 7. 推理模型的特殊支持

Google Gemini的推理模型（如gemini-2.5-flash）具有独特的思考过程输出能力。padwan-llm专门为此提供了支持：

```python
thoughts = []
async with GeminiClient(
    model="gemini-2.5-flash",
    on_thought=thoughts.append,
    thinking_config={"thinkingBudget": 2048, "includeThoughts": True},
) as client:
    stream = client.stream_chat([{"role": "user", "content": "7乘以8等于多少？"}])
    async for chunk in stream:
        print(chunk, end="")

print("\n---\n推理过程:", "".join(thoughts))
```

通过`on_thought`回调函数，应用可以实时接收模型的内部思考过程，与最终答案分离显示。这对于需要理解模型推理逻辑的场景非常有价值。

## 命令行界面

除了编程接口，padwan-llm还提供了一个简洁的命令行工具：

```bash
# 设置API密钥后
export OPENAI_API_KEY=...
padwan-llm "你好！" -m gpt-4o-mini

# 或者使用uvx直接运行，无需安装
uvx padwan-llm "你好！" -m gpt-4o-mini
```

这种设计方便了快速测试和脚本集成。

## 测试策略

项目采用了分层测试策略：

**单元测试**：无需API密钥即可运行，测试核心逻辑

```bash
uv run pytest
```

**端到端测试**：需要配置相应的API密钥，测试实际的提供商集成

```bash
uv run pytest tests/e2e/ -m e2e
uv run pytest tests/e2e/ -m e2e --env-file path/to/.env
```

缺少对应API密钥的测试会自动跳过，这种设计让开发者可以灵活选择测试范围。

## 与padwan-cli的关系

padwan-llm专注于提供底层的LLM客户端功能。如果开发者需要更丰富的交互式CLI或TUI（文本用户界面），可以使用配套的padwan-cli项目。这种分离设计遵循了Unix哲学：每个工具做好一件事，通过组合实现更复杂的功能。

## 应用场景

padwan-llm适合多种应用场景：

**AI应用开发**：作为后端服务的LLM调用层，统一处理多模型接入

**自动化脚本**：在数据处理、内容生成等批处理任务中调用LLM

**工具集成**：通过MCP协议将LLM能力接入现有工具链

**原型验证**：快速验证不同模型在特定任务上的表现，便于模型选型

**多租户系统**：通过统一的抽象层支持不同用户使用不同提供商的模型

## 技术亮点

### HTTP/2和HTTP/3支持

通过niquests库，padwan-llm自动协商使用HTTP/2或HTTP/3协议。相比HTTP/1.1，这些新协议提供了：

- 多路复用：单个连接上并行处理多个请求
- 头部压缩：减少传输开销
- 服务器推送：潜在的延迟优化

在高并发场景下，这些特性可以带来显著的性能提升。

### 类型安全

项目充分利用了Python的类型提示，提供了完整的类型注解。这不仅提升了代码的可读性，也让IDE能够提供更好的自动补全和错误检查。

### 资源管理

通过异步上下文管理器（async context managers），项目确保了HTTP连接、MCP会话等资源的生命周期得到妥善管理，避免资源泄漏。

## 总结

padwan-llm是一个设计精良、功能完善的LLM客户端库。它在保持极简依赖的同时，提供了丰富的功能特性：多提供商统一接口、异步支持、流式输出、AgentSession、MCP协议、推理模型特殊处理等。

对于Python开发者来说，如果你正在寻找一个轻量级、现代化、功能全面的LLM客户端，padwan-llm值得认真考虑。它既能满足简单的单次调用需求，也能支撑复杂的代理应用开发，是一个真正"小而美"的开源项目。