laiwenai 0.0.1

A lightweight OpenAI-compatible LLM client wrapper with defaults, retries, logging, and manual JSON mode.

LaiwenAI LLM Client

一个轻量的 OpenAI 兼容 Python 客户端封装，内置默认参数、重试机制、服务商校验和 logger 输出。

简体中文 · English

---

项目简介

LaiwenAI 让 OpenAI 兼容模型的调用更省心：你只需要在 .env 里配置一次默认服务商、模型、超时和重试策略，就可以继续使用熟悉的 OpenAI SDK 写法，同时获得默认参数注入、服务商切换保护和可选 logger 输出。

适合用于脚本、后端服务、原型验证，以及需要在多个 OpenAI 兼容服务之间切换的小型项目。

功能特性

• OpenAI SDK 兼容写法：继续使用 client.chat.completions.create(...)、client.embeddings.create(...) 等熟悉接口。
• 支持 OpenAI 兼容接口：通过 DEFAULT_BASE_URL 或实例化参数接入第三方兼容服务。
• 集中默认配置：统一管理默认模型、embedding 模型、温度、超时、重试次数和日志目录。
• 更安全的服务商切换：传入自定义 base_url 时必须显式传入 api_key，降低误用默认密钥的风险。
• 可选 logger 输出：可关闭、只输出到屏幕，或同时输出到屏幕和文件。

项目结构

.
├── .env.example          # 环境变量模板
├── LICENSE               # MIT 许可证
├── pyproject.toml        # Python 包配置
├── README.md             # 中文说明
├── README.EN.md          # English README
├── image/README/         # README 图片与 banner
├── docs/                 # 设计与代码说明
├── examples/             # 调用示例
├── tests/                # 单元测试
└── src/
    └── laiwenai/
        ├── __init__.py
        ├── llm_client.py        # LaiwenAI 客户端封装
        └── llm_config.py        # .env 配置读取

快速开始

1. 安装依赖

pip install laiwenai

2. 配置环境变量

cp .env.example .env

在 .env 中填入你的 API Key、OpenAI 兼容接口地址和默认模型：

LLM_API_KEY=your_api_key_here
DEFAULT_BASE_URL=https://api.example.com/v1
DEFAULT_MODEL=MiniMax-M2.7
DEFAULT_EMBEDDING_MODEL=text-embedding-3-small
DEFAULT_TEMPERATURE=0
DEFAULT_TIMEOUT=30.0
MAX_RETRIES=1
ENABLE_LOG_CONSOLE=False
ENABLE_LOG_FILE=False
LOG_DIR=logs

3. 检查默认行为

运行时配置都可以放在 .env 中：

DEFAULT_TEMPERATURE=0
DEFAULT_TIMEOUT=30.0
MAX_RETRIES=1
ENABLE_LOG_CONSOLE=False
ENABLE_LOG_FILE=False
LOG_DIR=logs

日志默认关闭。只想在屏幕显示日志时，将 ENABLE_LOG_CONSOLE 改为 True。如果将 ENABLE_LOG_FILE 改为 True，日志会同时输出到屏幕，并写入 LOG_DIR/laiwenai.log。LOG_DIR 默认是当前运行目录下的 logs/，也可以设置成你自己的日志目录。

4. 运行示例

python examples/llm.py

示例脚本会先发起一次 chat completion，再发起一次 embedding 请求，并打印模型回复或 embedding 向量维度。

使用方式

默认客户端

LaiwenAI() 会读取 .env 中的配置，并通过 laiwenai.llm_config 转换成运行时配置。

from laiwenai import LaiwenAI

client = LaiwenAI()

response = client.chat.completions.create(
    messages=[
        {"role": "user", "content": "Hello, please confirm your model version"}
    ]
)

print(response.choices[0].message.content)

请求默认值

model、temperature 和 timeout 不传或传入 None 时，会使用默认配置。Chat/Responses 请求默认使用 .env 里的 DEFAULT_MODEL，Embedding 请求默认使用 .env 里的 DEFAULT_EMBEDDING_MODEL。

response = client.chat.completions.create(
    model=None,
    messages=[{"role": "user", "content": "Hello"}],
    temperature=None,
    timeout=None,
)

Embedding 调用示例：

embedding = client.embeddings.create(input="Hello")
print(len(embedding.data[0].embedding))

JSON mode 等 OpenAI SDK 参数会原样透传给底层接口：

response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Return a JSON object"}],
    response_format={"type": "json_object"},
)

OpenAI 兼容接口

当你传入自定义 base_url 时，必须显式传入 api_key，避免把默认密钥误用于另一个服务商。

from laiwenai import LaiwenAI

client = LaiwenAI(
    api_key="your-provider-key",
    base_url="https://api.example.com/v1",
    model="MiniMax-M2.7",
)

内置使用帮助

from laiwenai import LaiwenAI

print(LaiwenAI.usage())

调用日志

默认不输出日志。将 .env 中的 ENABLE_LOG_CONSOLE 设置为 True 后，LaiwenAI 会把结构化日志输出到屏幕。将 ENABLE_LOG_FILE 设置为 True 后，LaiwenAI 会同时输出到屏幕，并追加写入 LOG_DIR/laiwenai.log。

日志包含时间、API 类型、模型、耗时、Token 用量、结束原因、系统提示词、用户提示词、回复文本和完整 JSON。

测试

PYTHONPATH=src pytest tests/test_llm.py -v

示例输出：

配置参考

配置项	文件	说明
LLM_API_KEY	.env	通过 python-dotenv 加载的默认 API Key。
DEFAULT_BASE_URL	.env	默认 OpenAI 兼容接口地址；不配置则使用 OpenAI SDK 默认地址。
DEFAULT_MODEL	.env	Chat/Responses 请求未指定模型时使用的模型；必须配置。
DEFAULT_EMBEDDING_MODEL	.env	Embedding 请求未指定模型时使用的模型；必须配置。
DEFAULT_TEMPERATURE	.env	请求未指定或传入 None 时使用的温度。
DEFAULT_TIMEOUT	.env	请求未指定或传入 None 时使用的超时时间。
MAX_RETRIES	.env	封装 API 调用的重试次数。
ENABLE_LOG_CONSOLE	.env	是否只输出屏幕日志。
ENABLE_LOG_FILE	.env	是否开启文件日志；开启后同时输出到屏幕和文件。
LOG_DIR	.env	文件日志目录；默认当前运行目录下的 logs。

参与贡献

欢迎提交 Issue 和 Pull Request。对于有行为变化的修改，建议附上简短说明、必要示例，以及能防止回归的测试。

开源协议

LaiwenAI 基于 MIT License 开源。