hyperagent-openai-gateway

<!-- LANGUAGE SWITCH --> [](README.md) [](README.vi.md) # 超级代理 → OpenAI 兼容 API 网关     **在 OpenAI 兼容的 API 后面运行 Hyperagent.com**。将任何 OpenAI 客户端（`openai` SDK、Cursor、Continue、LibreChat、LangChain 等）指向此网关，并调用您已经熟悉的端点 - `/v1/chat/completions`、`/v1/models`、`/v1/responses` 等。网关将每个请求转换为 Hyperagent 操作，并以确切的 OpenAI 线缆格式返回响应（包括流式传输）。 > **一句话：** 您的现有 OpenAI 代码继续有效，但回答问题的“模型”是一个完整的 Hyperagent **代理**，可以搜索网络、运行代码、使用浏览器、生成媒体和调用您的集成。 📚 **完整文档：** [英文文档](docs/en/00-index.md) · [越南语文档](docs/vi/00-index.md) --- ## 目录 - [这是什么？](#what-is-this) - [工作原理](#how-it-works) - [快速入门](#quick-start) - [连接您的客户端](#connect-your-client) - [支持的端点](#supported-endpoints) - [工具桥](#the-tool-bridge-shell-write-web-) - [多用户/多租户](#multi-user--multi-tenant) - [配置](#configuration) - [部署](#deployment) - [测试](#testing) - [项目结构](#project-structure) - [限制](#limitations) - [常见问题](#faq) - [许可证](#license) --- ## 这是什么？ **OpenAI API** 是一个事实上的标准：大量软件都懂得如何与它“对话”。**Hyperagent.com** 是一个平台，AI **代理** 在持久的 **线程** 中执行实际工作（研究、代码、浏览器自动化、媒体、文件、集成）。它的唯一公开编程门户是一个 **托管的 MCP 服务器**（模型上下文协议）- 不是 OpenAI 风格的 API。 该项目是这两个世界之间的 **适配器**。可以把它想象成一个通用电源插头：您的设备（OpenAI 客户端）以相同的方式插入，墙后电力实际上来自 Hyperagent。 **谁适合？** - 已经有基于 OpenAI 的应用程序，并希望在不重写代码的情况下使用代理后端的人员。 - 仅支持“OpenAI”（IDE、聊天 UI）但希望使用 Hyperagent 强大功能的工具。 不熟悉这些术语？从 [概述和概念](docs/en/01-overview.md) 开始。 ## 工作原理 ```text OpenAI 兼容客户端（Cursor、Continue、LibreChat、openai SDK 等） │ HTTP： POST /v1/chat/completions （Authorization：Bearer <网关密钥>） ▼ ┌───────────────────────────────────────────────┐ │ 网关（FastAPI） │ │ • 认证：网关密钥 → Hyperagent 身份 │ │ • 翻译：OpenAI ⇄ Hyperagent 线程操作 │ │ • 上游适配器： MCP（真实） | 模拟（开发） │ └───────────────────────────────────────────────┘ │ MCP JSON-RPC 2.0 HTTPS （OAuth 2.1 Bearer token） ▼ Hyperagent MCP 服务器 https://hyperagent.com/api/mcp │ list_agents · create_thread · get_thread （poll）· send_message · … ▼ 您的 Hyperagent 代理运行请求端到端 （网络搜索、浏览器、shell、文件、图像/音频、集成） ``` 关键思想： - **`模型` = Hyperagent 代理。** `GET /v1/models` 列出您的代理；选择一个作为 `模型`，或使用别名 `hyperagent-default`。 - **请求 = 线程运行。** Hyperagent 在后台运行，因此网关 **轮询** 直到答案准备好。 - **流式传输是模拟的。** Hyperagent 不流式传输令牌，因此网关将轮询更新转换为标准的 OpenAI SSE 数据块。 - **设计无状态。** 每个调用都是自包含的（参见 [架构](docs/en/03-architecture.md)）；网关从不依赖脆弱的上游内存。 ## 快速入门 **先决条件：** Python 3.11+（Docker 路径除外）。在 **Windows** 上，从 [python.org](https://www.python.org/downloads/) 安装 Python 并勾选 **“将 python.exe 添加到 PATH”** - 这也会为您提供 `py` 启动器。 **1. 安装 — 通用方式** （适用于 Windows、macOS、Linux）： ```bash pip install git+https://github.com/dinhhung893/hyperagent-openai-gateway ``` > Windows PowerShell：如果找不到 `pip`，请使用 `py -m pip install git+…`。 这提供了 `hyperagent-gateway` 命令（别名 `hga`）。如果您的 shell 找不到它，完全等效的方法始终有效：`python -m gateway.cli …`（Windows：`py -m gateway.cli …`）。 <details><summary><b>其他安装方法</b> — pipx · uv · Docker · 一行代码</summary> | 方法 | macOS / Linux | Windows (PowerShell) | | --- | --- | --- | | **pipx** | `pipx install git+…` | `py -m pip install --user pipx; py -m pipx ensurepath` → 重新打开 shell → `pipx install git+…` | | **uv** | `uvx --from git+… hyperagent-gateway serve` | `irm https://astral.sh/uv/install.ps1 \| iex` → `uvx --from git+… hyperagent-gateway serve` | | **Docker** | `docker compose up -d --build` | `docker compose up -d --build` | | **一行代码** | `curl -fsSL https://raw.githubusercontent.com/dinhhung893/hyperagent-openai-gateway/main/install.sh \| bash` | `irm https://raw.githubusercontent.com/dinhhung893/hyperagent-openai-gateway/main/install.ps1 \| iex` | > **Windows 注意：** 在 PowerShell 中，`curl` 是 `Invoke-WebRequest` 的别名，并且没有 `bash`，因此 `curl … \| bash` 行仅适用于 macOS/Linux/WSL。改为使用 `install.ps1`（通过 `irm … \| iex`）。 </details> **2. 上线 — 两个命令：** ```bash hga login # 一次性 Hyperagent 登录（打开浏览器） hga serve # 提供 http://localhost:8000/v1 ``` > 没有 PATH 命令的 Windows：`py -m gateway.cli login` 然后 `py -m gateway.cli serve`。 **仅试用？** 无需帐户 — 运行内置模拟： ```bash hga serve --upstream mock # 或： py -m gateway.cli serve --upstream mock ``` > 您的 Hyperagent 帐户需要至少一个 **命名代理** （MCP 服务器仅在命名代理上启动线程）。使用 `hga agents` 检查。 完整演练： [快速入门](docs/en/02-quickstart.md)。 ## 命令行界面 `hyperagent-gateway` （别名 `hga`）： | 命令 | 功能 | | --- | --- | | `hga init` | 编写 `~/.hyperagent-gateway/.env` （交互式； `--yes` 默认值） | | `hga login` | 一次性 OAuth（ `--remote-start` / `--remote-finish` 用于无头服务器） | | `hga serve` | 运行网关（ `--port` 、 `--upstream mcp\|mock` 、 `--reload` 等） | | `hga agents` | 列出您的 Hyperagent 代理 | | `hga doctor` | 检查配置 + 上游可达性 | | `hga quickstart` | `login` （如果需要）然后 `serve` | **自动加载配置** 优先级：CLI 标志 → 环境 → `.env` （当前目录，然后 `~/.hyperagent-gateway/.env` ）→ 默认值。所以您可以删除一个 `.env` 并跳过长环境变量。（ `uvicorn gateway.app:app` 仍然适用于高级用户。） ## 认证（API 密钥） 有两个独立的凭证 — 不要混淆： **1. 您的网关 API 密钥** （`SHIM_API_KEYS`）- 您的 OpenAI 客户端发送的 `api_key`。 **您自己选择它；它不会从任何地方获取。** `hga init` 和安装程序为您自动生成一个。 - **查看它：** `cat ~/.hyperagent-gateway/.env` （Windows PowerShell： `Get-Content $env:USERPROFILE\.hyperagent-gateway\.env` ）- 查找 `SHIM_API_KEYS=` 行。 - **设置/生成它：** `hga init` （向导），或编辑 `.env` （`SHIM_API_KEYS=sk-yourkey` ；用逗号分隔多个），或将 `--api-keys` 传递给 `serve`。 - **开发模式：** 如果 `SHIM_API_KEYS` 未设置，网关接受 *任何* 密钥 - 但您的客户端仍然需要一个 **非空** 值，因此只需输入 `sk-local` （大多数 OpenAI 工具需要非空 `api_key` ，有些需要 `sk-` 前缀）。 **2. 您的 Hyperagent 访问** - Hyperagent 没有 **API 密钥**。网关使用 OAuth 登录一次（`hga login`）并存储一个可刷新的令牌；您永远不会粘贴 Hyperagent 密钥。 因此： `hga login` 处理 Hyperagent； `SHIM_API_KEYS` 是一个您设置的秘密 **，用于保护网关** ，它是客户端用作其 `api_key` 的内容。 ## 连接您的客户端 **OpenAI Python SDK** ```python from openai import OpenAI client = OpenAI(base_url="http://localhost:8000/v1", api_key="sk-mylocalkey") print(client.models.list()) # 您的 Hyperagent 代理 r = client.chat.completions.create( model="hyperagent-default", messages=[{"role": "user", "content": "Research the latest on X and summarize"}], ) print(r.choices[0].message.content) ``` **curl（macOS / Linux）** ```bash curl http://localhost:8000/v1/chat/completions \ -H "authorization: Bearer sk-mylocalkey" -H "content-type: application/json" \ -d '{"model":"hyperagent-default","messages":[{"role":"user","content":"Hello"}]}' ``` **PowerShell（Windows）** — 那里的 `curl` 是 `Invoke-WebRequest` ，因此使用： ```powershell Invoke-RestMethod -Uri http://localhost:8000/v1/chat/completions -Method Post ` -Headers @{ Authorization = "Bearer sk-mylocalkey" } -ContentType 'application/json' ` -Body '{"model":"hyperagent-default","messages":[{"role":"user","content":"Hello"}]}' ``` > 非 ASCII 正文（越南语等）也有效 - 网关自动修复 Windows Latin-1/CP1252 编码。对于严格的正确性，请使用 PowerShell 7。 **Cursor / Continue / LibreChat / OpenWebUI：** 将 OpenAI **Base URL** 设置为 `http://localhost:8000/v1` ，将 **API 密钥** 设置为您的 `SHIM_API_KEYS` 之一，并将 **模型** 设置为 `GET /v1/models` 中的代理 ID。 ## 支持的端点 | 端点 | 状态 | | --- | --- | | `GET /v1/models` ， `/v1/models/{id}` | ✅ 列出您的 Hyperagent 代理 | | `POST /v1/chat/completions` （流式 + 非流式） | ✅ | | `POST /v1/responses` （+ background，cancel，input_items，stateful chains） | ✅ | | `GET /v1/tools` + 强制 `tool_choice` | ✅ 工具桥 | | `POST /v1/completions` （旧版） | ✅ | | `POST /v1/images/generations` ， `/v1/images/edits` | ✅ 真实可获取的 URL | | `POST /v1/audio/speech` ， `/transcriptions` ， `/translations` | ✅ | | `POST /v1/files` ， `GET/DELETE /v1/files/{id}` ， `/content` | ✅ + 聊天附件 | | `POST /v1/embeddings` | ✅ 本地回退（或 `501` 如果禁用） | | `POST /v1/moderations` | ✅ 启发式 | 完整参数行为： [API 参考](docs/en/04-api-reference.md)。 ## 工具桥（Shell，Write，web，...） Hyperagent 代理具有丰富的工具箱（bash/shell，文件读写，网络搜索，浏览器，图像/视频/音频，表格，文档，地图，集成）。网关通过 OpenAI 的标准 `tools` / `tool_calls` 以三种模式公开所有这些工具： - **观察** - 代理的工具活动作为 `tool_calls` 显示在回复中。 - **直接** - 使用 `tool_choice` 强制执行功能。 - **运行** - 工具运行器直接执行工具（例如运行 shell 命令）并返回结果。 `GET /v1/tools` 返回完整的目录。详情和示例： [工具桥](docs/en/05-tool-bridge.md)。 ## 多用户/多租户 一个网关可以为多个 Hyperagent 用户服务。使用 `GATEWAY_KEYS_FILE` 将每个 API 密钥映射到其自己的 Hyperagent 身份和策略： ```json [{"api_key":"sk-alice","token_file":"~/.hyperagent-gateway/alice.json","disabled_tools":["shell"]}, {"api_key":"sk-bob","token_file":"~/.hyperagent-gateway/bob.json"}] ``` 每个用户使用 `tools/oauth_login.py` 进行身份验证。参见 [部署和安全](docs/en/06-deployment.md)。 ## 配置 | 变量 | 默认值 | 含义 | | --- | --- | --- | | `GATEWAY_UPSTREAM` | `mcp` | `mcp` （真实）或 `mock` （离线） | | `HYPERAGENT_MCP_URL` | `https://hyperagent.com/api/mcp` | 上游端点 | | `HYPERAGENT_TOKEN_FILE` | `~/.hyperagent-gateway/tokens.json` | OAuth 令牌包 | | `SHIM_API_KEYS` | （空 = 开发；客户端仍然发送任意非空密钥，例如 `sk-local`） | 用逗号分隔的客户端密钥 | | `GATEWAY_KEYS_FILE` | （无） | 多租户身份映射（JSON） | | `GATEWAY_DEFAULT_AGENT` | （第一个代理） | `hyperagent-default` 的代理 | | `GATEWAY_EXEC_MODE` | `roundtrip` | 工具运行器模式： `roundtrip` 或 `auto` | | `GATEWAY_DISABLED_TOOLS` | （无） | 隐藏工具，例如 `shell,write_file` | | `GATEWAY_EMBEDDINGS` | `fallback` | `fallback` 或 `off` | | `GATEWAY_POLL_INTERVAL` / `GATEWAY_RUN_TIMEOUT` | `1.0` / `600` | 轮询 | ## 部署 Docker Compose（推荐用于服务器）- 将设置放入 `.env` 并将令牌包放入 `./secrets/tokens.json`： ```bash docker compose up -d --build ``` 完整指南（VPS，反向代理，HTTPS，多租户，无头 OAuth）： [部署](docs/en/06-deployment.md)。 ## 测试 ```bash python3.11 -m pytest tests/ -q # 46 测试：单元 + ASGI API + OpenAI SDK ``` ## 项目结构 ```text gateway/ FastAPI 应用程序 + 翻译 + 上游适配器 app.py 所有 HTTP 路由 upstream/ mcp.py （真实） · mock.py （开发） · base.py · manager.py translate.py streaming.py toolbridge.py fallbacks.py media.py auth.py … tools/ oauth_login.py, oauth_remote.py （一次性 OAuth 帮助程序） tests/ 46 测试（模拟上游 + OpenAI SDK） docs/en/ docs/vi/ 双语文档 Dockerfile requirements.txt pyproject.toml ``` ## 限制 - **延迟：** 每个调用运行一个完整的代理管道 - 预计几秒钟，而不是毫秒。 - **流式传输是模拟的** （基于轮询），不是真正的令牌流式传输。 - **采样旋钮** （`temperature` ， `top_p` ， `seed` ）是尽力而为 / 无操作。 - **嵌入** 使用本地非语义回退，除非您配置了一个真正的提供者。 - **身份验证** 按用户 OAuth（Hyperagent 没有 API 密钥）；网关存储并刷新每个用户的令牌。 ## 常见问题 一些快速问题（完整列表： [FAQ](docs/en/07-faq.md)）： - **我需要更改我的 OpenAI 代码吗？** 不 - 只是 `base_url` 和 `api_key`。 - **我传递哪个模型？** Hyperagent 代理 ID （ `GET /v1/models` ）或 `hyperagent-default`。 - **它真的兼容 OpenAI 吗？** 是的；官方 `openai` SDK 无修改后可使用（已测试）。 ## 许可证 没有包含许可证文件。添加许可证文件之前，所有权利由存储库所有者保留。打开一个问题，如果您需要特定的许可证（例如 MIT）。 _{构建于 Hyperagent MCP 服务器。“OpenAI” 是 OpenAI 的商标；该项目是一个独立的兼容层，与 OpenAI 无伙计。}