ai-gateways 1.0.0

统一的 AI Gateway 包，支持 Azure OpenAI、OpenRouter 和 Skywork 三种服务商

AI Gateway 统一调用包

统一的 AI Gateway 包，支持 Azure OpenAI、OpenRouter 和 Skywork 三种服务商，通过指定服务商和模型名即可最简化调用。

🚀 快速开始

1. 安装包

方式一：从源码安装（推荐）

# 克隆或下载项目
git clone <your-repo-url>
cd gateways

# 安装包（开发模式，修改代码后立即生效）
pip install -e .

方式二：从本地安装

# 在项目根目录执行
pip install .

方式三：构建分发包后安装

# 安装构建工具（如果还没有）
pip install setuptools wheel

# 构建分发包
python setup.py sdist bdist_wheel

# 安装分发包
pip install dist/ai-gateways-1.0.0.tar.gz
# 或使用 wheel 文件
pip install dist/ai_gateways-1.0.0-py3-none-any.whl

方式四：发布到 PyPI 后安装（如果已发布）

pip install ai-gateways

安装完成后，包会自动安装所有依赖：

• openai>=1.0.0
• python-dotenv>=1.0.0
• requests>=2.31.0
• urllib3>=1.26.0

2. 配置 API Key

重要： 你的 API key 是隐私信息，不会被包含在包中。你需要自己配置。

有两种方式配置 API key：

方式一：使用代码配置（推荐，更安全）

from gateways import configure_api_keys, chat

# 配置 API key
configure_api_keys(
    azure_api_key="your-azure-api-key",
    azure_endpoint="https://your-endpoint.cognitiveservices.azure.com/",
    openrouter_api_key="your-openrouter-api-key",
)

# 使用
reply = chat("你好", "gpt-4o-mini", provider="azure")

方式二：使用 .env 文件

1. 复制模板文件：

cp .env.example .env

2. 编辑 .env 文件，填写你的真实 API key：

# Azure OpenAI（可选）
AZURE_OPENAI_API_KEY=your-azure-api-key
AZURE_OPENAI_ENDPOINT=https://your-endpoint.cognitiveservices.azure.com/

# OpenRouter（可选）
OPENROUTER_API_KEY=your-openrouter-api-key
OPENROUTER_SITE_URL=https://your-site.com  # 可选
OPENROUTER_SITE_NAME=Your Site Name        # 可选

# Skywork（可选，支持 GPT 和 Gemini）
# 如果使用 GPT 模型，需要配置：
OPENAI_BASE_URL=your-openai-base-url
OPENAI_API_KEY=your-openai-api-key
# 如果使用 Gemini 模型，需要配置：
GOOGLE_BASE_URL=your-google-base-url
GOOGLE_API_KEY=your-google-api-key

注意：

• .env 文件不会被上传到 PyPI，你的 API key 是安全的
• 所有服务商的 API key 都统一放在根目录的 .env 文件中
• 至少需要配置一个服务商的 API key
• 推荐使用 configure_api_keys() 函数配置，更安全

3. 使用

from gateways import chat

# 使用统一模型名（推荐）✨
# 系统会自动将 'gpt-4o-mini' 映射到各服务商的实际模型名
reply = chat("你好", "gpt-4o-mini", provider="azure")      # Azure: gpt-4o-mini
reply = chat("你好", "gpt-4o-mini", provider="openrouter")  # OpenRouter: openai/gpt-4o-mini
reply = chat("你好", "gpt-4o", provider="skywork")         # Skywork: gpt-4o
reply = chat("你好", "gemini-2.5-pro", provider="skywork")  # Skywork: gemini-2.5-pro

# 如果不指定provider，会自动检测可用的服务商
reply = chat("你好", "gpt-4o-mini")  # 自动使用Azure（如果已配置）

# 也可以直接使用完整模型ID（向后兼容）
reply = chat("你好", "openai/gpt-4o-mini", provider="openrouter")

📖 API 文档

chat(prompt, model, provider=None, **kwargs)

同步调用 AI 模型（最简单的方式）

参数：

• prompt (str): 用户消息
• model (str): 统一模型名称（推荐），如 'gpt-4o-mini'
  • 系统会自动映射到各服务商的实际模型名
  • Azure: 'gpt-4o-mini' → 'gpt-4o-mini' (部署名称)
  • OpenRouter: 'gpt-4o-mini' → 'openai/gpt-4o-mini'
  • 也支持直接使用完整模型ID（如 'openai/gpt-4o-mini'），会直接使用
• provider (str, 可选): 服务商 ('azure' 或 'openrouter')，如果为None则自动检测
• **kwargs: 其他参数（temperature, max_tokens等）

返回：

• str: 模型回复内容

示例：

from gateways import chat

# 使用统一模型名（推荐）✨
reply = chat("解释什么是人工智能", "gpt-4o-mini", provider="azure", temperature=0.7)
reply = chat("解释什么是人工智能", "gpt-4o-mini", provider="openrouter")  # 自动映射为 openai/gpt-4o-mini

# 使用OpenRouter的其他模型
reply = chat("解释什么是人工智能", "claude-3-haiku", provider="openrouter")  # 自动映射为 anthropic/claude-3-haiku
reply = chat("解释什么是人工智能", "gemma-free", provider="openrouter")  # 自动映射为 google/gemma-3n-e2b-it:free

# 也可以直接使用完整模型ID（向后兼容）
reply = chat("解释什么是人工智能", "openai/gpt-4o-mini", provider="openrouter")

chat_async(prompt, model, provider=None, **kwargs)

异步调用 AI 模型

示例：

import asyncio
from gateways import chat_async

async def main():
    reply = await chat_async("你好", "gpt-4o-mini", provider="azure")
    print(reply)

asyncio.run(main())

chat_with_history(messages, model, provider=None, **kwargs)

使用消息历史进行对话

示例：

from gateways import chat_with_history

messages = [
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好！有什么可以帮助你的？"},
    {"role": "user", "content": "今天天气怎么样？"}
]

reply = chat_with_history(messages, "gpt-4o-mini", provider="azure")

get_client(provider=None, async_mode=False, **kwargs)

获取客户端实例（高级用法）

示例：

from gateways import get_client

client = get_client(provider="azure")
completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}]
)

set_provider(provider)

设置默认服务商

示例：

from gateways import set_provider

set_provider("azure")  # 设置Azure为默认服务商
reply = chat("你好", "gpt-4o-mini")  # 自动使用Azure

configure_api_keys(...)

通过代码配置 API key（优先于环境变量）

参数：

• azure_api_key: Azure OpenAI API key
• azure_endpoint: Azure OpenAI endpoint
• openrouter_api_key: OpenRouter API key
• openrouter_site_url: OpenRouter site URL（可选）
• openrouter_site_name: OpenRouter site name（可选）
• skywork_openai_base_url: Skywork OpenAI base URL
• skywork_openai_api_key: Skywork OpenAI API key
• skywork_google_base_url: Skywork Google base URL
• skywork_google_api_key: Skywork Google API key

示例：

from gateways import configure_api_keys, chat

# 配置 API key
configure_api_keys(
    azure_api_key="your-azure-key",
    azure_endpoint="https://your-endpoint.cognitiveservices.azure.com/",
    openrouter_api_key="your-openrouter-key",
)

# 使用
reply = chat("你好", "gpt-4o-mini", provider="azure")

注意： 代码配置的 key 会优先于环境变量使用。

🎯 常用模型（统一模型名）

通用模型（所有服务商都支持）

• gpt-4o-mini - GPT-4o Mini（推荐，快速且经济）
• gpt-4o - GPT-4o（最新模型）
• gpt-4-turbo - GPT-4 Turbo

OpenRouter 特有模型

• claude-3-haiku - Claude 3 Haiku（快速且便宜）
• claude-3-sonnet - Claude 3 Sonnet（平衡）
• claude-3-opus - Claude 3 Opus（最强）
• gemma-free - Google Gemma（免费）
• gemini-free - Google Gemini 2.0 Flash（免费）
• gemini-pro - Google Gemini Pro
• llama-3.3-8b - Llama 3.3 8B（免费）
• llama-3.1-8b - Llama 3.1 8B（免费）

Skywork 特有模型

GPT 模型：

• gpt-4o-mini - GPT-4o Mini
• gpt-4o - GPT-4o
• gpt-4o-2024-11-20 - GPT-4o 特定版本
• gpt-4 - GPT-4
• gpt-4.1 - GPT-4.1

Gemini 模型：

• gemini-2.5-pro - Gemini 2.5 Pro（最佳性能）
• gemini-2.5-flash - Gemini 2.5 Flash（快速）
• gemini-2.0-flash - Gemini 2.0 Flash
• gemini-2.5-flash-preview - Gemini 2.5 Flash 预览版
• gemini-2.5-flash-lite - Gemini 2.5 Flash Lite
• gemini-2.0-flash-lite - Gemini 2.0 Flash Lite

查看所有可用模型

from gateways import get_available_models

# 查看所有服务商的模型映射
models = get_available_models()

# 查看特定服务商的模型
azure_models = get_available_models("azure")
openrouter_models = get_available_models("openrouter")

注意： 使用统一模型名时，系统会自动映射到各服务商的实际模型名。例如：

• gpt-4o-mini 在 Azure 中映射为 gpt-4o-mini
• gpt-4o-mini 在 OpenRouter 中映射为 openai/gpt-4o-mini

💡 使用示例

基础用法（使用统一模型名）

from gateways import chat

# 使用统一模型名，系统自动映射
reply = chat("什么是人工智能？", "gpt-4o-mini", provider="azure")
print(reply)

# 同样的模型名，不同的服务商
reply_azure = chat("什么是人工智能？", "gpt-4o-mini", provider="azure")
reply_openrouter = chat("什么是人工智能？", "gpt-4o-mini", provider="openrouter")

指定参数

from gateways import chat

reply = chat(
    "写一首关于春天的诗",
    "gpt-4o-mini",
    provider="azure",
    temperature=0.8,
    max_tokens=500
)

多轮对话

from gateways import chat_with_history

messages = [
    {"role": "system", "content": "你是一个友好的助手"},
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好！有什么可以帮助你的？"},
    {"role": "user", "content": "告诉我一个笑话"}
]

reply = chat_with_history(messages, "gpt-4o-mini", provider="azure")
print(reply)

异步调用

import asyncio
from gateways import chat_async

async def main():
    tasks = [
        chat_async("什么是AI？", "gpt-4o-mini", provider="azure"),
        chat_async("什么是机器学习？", "gpt-4o-mini", provider="azure"),
    ]
    replies = await asyncio.gather(*tasks)
    for reply in replies:
        print(reply)

asyncio.run(main())

🔧 配置说明

自动检测服务商

如果不指定 provider，系统会按以下顺序自动检测：

1. 如果设置了默认服务商（通过 set_provider()），使用默认服务商
2. 如果配置了 Azure（AZURE_OPENAI_API_KEY 和 AZURE_OPENAI_ENDPOINT），使用 Azure
3. 如果配置了 OpenRouter（OPENROUTER_API_KEY），使用 OpenRouter
4. 如果都没有配置，抛出错误

环境变量

Azure OpenAI:

• AZURE_OPENAI_API_KEY - API密钥（必需）
• AZURE_OPENAI_ENDPOINT - 端点URL（必需）

OpenRouter:

• OPENROUTER_API_KEY - API密钥（必需）
• OPENROUTER_SITE_URL - 网站URL（可选）
• OPENROUTER_SITE_NAME - 网站名称（可选）

Skywork:

• OPENAI_BASE_URL - OpenAI API 基础URL（用于 GPT 模型）
• OPENAI_API_KEY - OpenAI API 密钥（用于 GPT 模型）
• GOOGLE_BASE_URL - Google API 基础URL（用于 Gemini 模型）
• GOOGLE_API_KEY - Google API 密钥（用于 Gemini 模型）

注意： 不再需要在子目录（azure/、openrouter/ 或 skywork/）下单独配置 .env 文件，所有配置都统一在根目录的 .env 文件中。

📁 项目结构

gateways/
├── __init__.py          # 包入口
├── gateway.py           # 核心实现
├── requirements.txt     # 依赖
├── README.md           # 文档
├── azure/              # Azure相关文件
└── openrouter/         # OpenRouter相关文件

⚡ 特性

• ✅ 统一接口 - 一个API支持多个服务商
• ✅ 自动检测 - 自动选择可用的服务商
• ✅ 客户端缓存 - 自动复用连接，提高性能
• ✅ 同步/异步 - 支持同步和异步调用
• ✅ 简单易用 - 一行代码即可调用
• ✅ 灵活配置 - 支持环境变量和代码配置

🆘 故障排查

错误：未找到可用的服务商配置

确保至少配置了一个服务商的 API key 和必要的环境变量。

错误：不支持的提供商

确保 provider 参数是 'azure' 或 'openrouter'。

Azure 调用失败

检查：

1. AZURE_OPENAI_API_KEY 是否正确
2. AZURE_OPENAI_ENDPOINT 是否正确
3. 模型部署名称是否正确

OpenRouter 调用失败

检查：

1. OPENROUTER_API_KEY 是否正确
2. 账户余额是否充足
3. 模型ID是否正确（格式：provider/model-name）