🤖 smithery-2api 🤖

将 Smithery.ai 强大的 AI 模型能力无缝转换为兼容 OpenAI API 格式的转换器

"任何足够先进的技术，都与魔法无异。" —— 亚瑟·克拉克

我们不创造魔法，我们只是让每个人都能成为魔法师。smithery-2api 的诞生，源于一个简单的信念：强大的工具应该被更广泛、更便捷地使用。我们希望通过这个项目，打破平台的壁垒，将 Smithery.ai 先进的模型能力，注入到每一个支持 OpenAI API 的应用生态中。

✨ 核心特性

🚀 零成本接入 - 免费将 Smithery.ai 的多种模型接入现有 OpenAI 生态
🔌 高度兼容 - 完全模拟 OpenAI 的 /v1/chat/completions 和 /v1/models 接口
🔄 多账号轮询 - 支持配置多个 Smithery.ai 账号，自动轮询提高稳定性
💨 无状态设计 - 极致轻量，易于水平扩展，保护用户隐私
☁️ 穿透 Cloudflare - 内置自动处理 Cloudflare 防护机制
📦 Docker 一键部署 - 一条命令即可启动服务
🔓 开源自由 - 采用 Apache 2.0 协议，自由使用、修改和分发

🏗️ 架构设计

核心工作原理

smithery-2api 充当一个智能的协议转换器，在 OpenAI API 格式和 Smithery.ai 内部 API 格式之间进行实时转换。

graph TB
    Client[第三方应用] -->|OpenAI 格式请求| API[smithery-2api]
    API -->|协议转换| Translator[API 转换器]
    Translator -->|身份伪装| Identity[身份伪装模块]
    Identity -->|Smithery 格式请求| Smithery[Smithery.ai 服务]
    Smithery -->|流式响应| API
    API -->|OpenAI 格式响应| Client
    
    subgraph "转换过程详解"
        Translator --> Format[格式转换]
        Identity --> Headers[请求头模拟]
        Identity --> Cookie[Cookie 处理]
        Identity --> Cloudflare[Cloudflare 穿透]
    end

技术实现细节

1. API 格式转换

技术核心: app/providers/smithery_provider.py 中的 _convert_messages_to_smithery_format 方法

转换示例:

输入 (OpenAI 格式):

{
  "model": "gpt-4",
  "messages": [
    {"role": "user", "content": "你好，请介绍一下自己"}
  ],
  "stream": true
}

输出 (Smithery.ai 格式):

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "user", 
      "parts": [{"type": "text", "text": "你好，请介绍一下自己"}],
      "id": "msg-xxxxxxxx"
    }
  ],
  "stream": true
}

2. 身份认证与伪装

技术核心: app/core/config.py 中的 AuthCookie 类

class AuthCookie(BaseModel):
    """Smithery 认证 Cookie 数据结构"""
    access_token: str
    token_type: str = "bearer"
    expires_in: int
    refresh_token: str
    user: Dict[str, Any]
    
    @property
    def header_cookie_string(self) -> str:
        """生成请求头中的 Cookie 字符串"""
        return f"sb-access-token={self.access_token}; sb-refresh-token={self.refresh_token}"

3. 流式响应处理

技术核心: app/utils/sse_utils.py 和流式响应处理逻辑

async def handle_stream_response(response, model: str):
    """处理流式响应并转换为 OpenAI 格式"""
    async for line in response.iter_lines():
        if line.startswith('data: '):
            data = line[6:]  # 移除 'data: ' 前缀
            if data == '[DONE]':
                yield create_chat_completion_chunk("", "", finish_reason="stop")
                break
            # 解析和转换数据...
            yield f"data: {json.dumps(converted_data)}\n\n"

🚀 快速开始

环境要求

Git - 版本控制工具
Docker & Docker Compose - 容器化部署

部署步骤

步骤 1: 获取项目代码

git clone https://github.com/lzA6/smithery-2api.git
cd smithery-2api

步骤 2: 获取认证信息

在浏览器中登录 Smithery.ai
打开开发者工具 (F12)
切换到 Application → Local Storage → https://smithery.ai
找到 key 为 sb-spjawbfpwezjfmicopsl-auth-token 的项
复制完整的 value 值（JSON 格式）

步骤 3: 配置环境变量

# 复制环境配置模板
cp .env.example .env

# 编辑配置文件
vim .env

环境变量配置示例:

# API 主密钥（用于客户端认证）
API_MASTER_KEY="your-secure-master-key-here"

# Smithery.ai 认证信息（支持多个账号）
SMITHERY_COOKIE_1='{"access_token":"eyJ...","token_type":"bearer","expires_in":3600,...}'
SMITHERY_COOKIE_2='{"access_token":"eyJ...","token_type":"bearer","expires_in":3600,...}'

# 服务端口配置
NGINX_PORT=8088
APP_PORT=8000

步骤 4: 启动服务

docker-compose up -d

步骤 5: 验证部署

使用 curl 测试服务是否正常运行：

curl -X GET "http://localhost:8088/v1/models" \
  -H "Authorization: Bearer your-secure-master-key-here"

客户端配置示例

OpenAI 官方客户端:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8088/v1",
    api_key="your-secure-master-key-here"
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello, world!"}],
    stream=True
)

第三方应用配置:

Base URL: http://localhost:8088/v1
API Key: your-secure-master-key-here
Model: 任意支持的模型名称

🛠️ 技术架构

技术栈

技术组件	版本	用途	关键特性
FastAPI	0.104+	Web 框架	异步支持，自动文档生成
Pydantic	2.5+	数据验证	类型提示，配置管理
Cloudscraper	1.2+	反爬虫绕过	Cloudflare 穿透
Uvicorn	0.24+	ASGI 服务器	高性能异步服务器
Docker	20.10+	容器化	环境隔离，一键部署
Nginx	1.24+	反向代理	负载均衡，静态文件服务

项目结构

smithery-2api/
├── 📁 app/                          # 应用核心代码
│   ├── 📁 core/                     # 核心模块
│   │   ├── __init__.py
│   │   └── config.py               # 配置管理，环境变量处理
│   ├── 📁 providers/               # 服务提供商模块
│   │   ├── __init__.py
│   │   ├── base_provider.py        # 提供商基类
│   │   └── smithery_provider.py    # Smithery.ai 提供商实现
│   ├── 📁 services/                # 业务服务层
│   │   ├── session_manager.py      # 会话管理（预留）
│   │   └── tool_caller.py          # 工具调用（预留）
│   └── 📁 utils/                   # 工具函数
│       └── sse_utils.py           # Server-Sent Events 工具
├── 📄 main.py                      # FastAPI 应用入口
├── 📄 nginx.conf                   # Nginx 配置
├── 📄 Dockerfile                   # 应用镜像构建配置
├── 📄 docker-compose.yml           # 服务编排配置
├── 📄 requirements.txt             # Python 依赖
└── 📄 .env.example                 # 环境变量模板

核心模块详解

1. 配置管理 (`app/core/config.py`)

class Settings(BaseSettings):
    """应用配置类"""
    API_MASTER_KEY: str
    SMITHERY_COOKIE_1: Optional[str] = None
    SMITHERY_COOKIE_2: Optional[str] = None
    NGINX_PORT: int = 8088
    APP_PORT: int = 8000
    
    @property
    def AUTH_COOKIES(self) -> List[AuthCookie]:
        """获取所有可用的认证 Cookie"""
        cookies = []
        for i in range(1, 3):
            if cookie_str := getattr(self, f"SMITHERY_COOKIE_{i}", None):
                try:
                    cookies.append(AuthCookie.parse_raw(cookie_str))
                except ValidationError as e:
                    logger.warning(f"Invalid cookie format for SMITHERY_COOKIE_{i}: {e}")
        return cookies

settings = Settings()

2. Smithery 提供商 (`app/providers/smithery_provider.py`)

class SmitheryProvider(BaseProvider):
    """Smithery.ai 服务提供商"""
    
    async def chat_completion(self, request: ChatCompletionRequest) -> StreamingResponse:
        """处理聊天补全请求"""
        
        # 1. 轮询获取可用 Cookie
        auth_cookie = self._get_cookie()
        
        # 2. 准备请求头和负载
        headers = self._prepare_headers(auth_cookie)
        payload = self._prepare_payload(request)
        
        # 3. 发送请求到 Smithery.ai
        response = self._make_request(headers, payload)
        
        # 4. 处理流式响应
        return self._handle_stream_response(response, request.model)

    def _convert_messages_to_smithery_format(self, messages: List[Dict]) -> List[Dict]:
        """将 OpenAI 消息格式转换为 Smithery 格式"""
        converted_messages = []
        for msg in messages:
            converted_msg = {
                "role": msg["role"],
                "parts": [{"type": "text", "text": msg["content"]}],
                "id": f"msg-{str(uuid.uuid4())[:8]}"
            }
            converted_messages.append(converted_msg)
        return converted_messages

🔧 高级配置

多账号负载均衡

支持配置多个 Smithery.ai 账号实现自动轮询：

# 配置多个账号提高可用性
SMITHERY_COOKIE_1='{"access_token":"token1","refresh_token":"refresh1",...}'
SMITHERY_COOKIE_2='{"access_token":"token2","refresh_token":"refresh2",...}'
SMITHERY_COOKIE_3='{"access_token":"token3","refresh_token":"refresh3",...}'

自定义模型映射

在 smithery_provider.py 中配置模型映射关系：

MODEL_MAPPING = {
    "gpt-4": "gpt-4",
    "gpt-3.5-turbo": "claude-haiku-4.5", 
    "claude-3-opus": "claude-opus-3.0"
}

Nginx 优化配置

# nginx.conf
server {
    listen 8088;
    client_max_body_size 100M;
    client_body_timeout 300s;
    
    location / {
        proxy_pass http://app:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # 流式响应相关配置
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 300s;
    }
}

🐛 故障排除

常见问题

1. 认证失败

错误信息: Authentication failed or cookie expired
解决方案: 重新获取 SMITHERY_COOKIE 值

2. Cloudflare 拦截

错误信息: 403 Forbidden or Cloudflare challenge
解决方案: 确保 cloudscraper 版本最新，或更新请求头信息

3. 流式响应中断

错误信息: 连接提前关闭
解决方案: 检查客户端超时设置，确保网络稳定性

日志调试

启用详细日志输出：

import logging
logging.basicConfig(level=logging.DEBUG)

健康检查

# 检查服务状态
curl -X GET "http://localhost:8088/health"

# 检查模型列表
curl -X GET "http://localhost:8088/v1/models" \
  -H "Authorization: Bearer your-api-key"

🚧 限制与待完善功能

当前限制

令牌过期处理 - 当前未实现自动刷新机制
错误处理 - 错误信息返回可以更加友好
速率限制 - 缺少请求频率限制
会话管理 - 无状态设计，客户端需维护完整上下文

开发路线图

自动令牌刷新机制
- 利用 refresh_token 自动更新 access_token
- 实现令牌过期前预刷新
增强的错误处理
- 更友好的错误消息
- 重试机制和故障转移
会话状态管理
- 可选的有状态会话模式
- Redis 后端支持
监控和指标
- Prometheus 指标收集
- 请求统计和性能监控
扩展提供商支持
- 支持其他 AI 服务平台
- 统一的提供商接口

🤝 贡献指南

我们欢迎各种形式的贡献！

报告问题

如果您发现任何问题，请通过 GitHub Issues 报告。

代码贡献

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

开发环境设置

# 克隆仓库
git clone https://github.com/lzA6/smithery-2api.git
cd smithery-2api

# 安装依赖
pip install -r requirements.txt

# 设置环境变量
cp .env.example .env
# 编辑 .env 文件配置认证信息

# 启动开发服务器
uvicorn main:app --reload --port 8000

📄 许可证

本项目采用 Apache 2.0 许可证 - 详见 LICENSE 文件。

🙏 致谢

感谢所有为这个项目做出贡献的开发者，以及 Smithery.ai 提供的优秀 AI 服务。

🔗 有用链接

如果这个项目对您有帮助，请给个 ⭐️ 支持一下！

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
app		app
.env		.env
.env.example		.env.example
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
main.py		main.py
nginx.conf		nginx.conf
requirements.txt		requirements.txt
项目完整结构代码.txt		项目完整结构代码.txt

License

copilot1996/smithery-2api

Folders and files

Latest commit

History

Repository files navigation