vertext-ai-proxy 0.2.1__tar.gz

vertext_ai_proxy-0.2.1/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: vertext-ai-proxy
+Version: 0.2.1
+Summary: 轻量级 Google Cloud Vertex AI（Gemini Enterprise Agent Platform）OpenAI 协议反向代理网关
+Keywords: vertex-ai,gemini,openai,reverse-proxy,llm,embeddings
+Author: entr0pia
+Author-email: entr0pia <30486766+entr0pia@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: fastapi>=0.162.0
+Requires-Dist: google-auth>=2.62.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: requests>=2.34.2
+Requires-Dist: uvicorn>=0.54.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/entr0pia/vertext-ai-proxy
+Project-URL: Repository, https://github.com/entr0pia/vertext-ai-proxy
+Project-URL: Issues, https://github.com/entr0pia/vertext-ai-proxy/issues
+Description-Content-Type: text/markdown
+
+# Vertex AI OpenAI Proxy
+
+[![PyPI version](https://img.shields.io/pypi/v/vertext-ai-proxy.svg)](https://pypi.org/project/vertext-ai-proxy/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://pypi.org/project/vertext-ai-proxy/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+轻量级 Google Cloud Vertex AI（Gemini Enterprise Agent Platform）OpenAI 协议反向代理网关。
+
+将 Google Cloud 的服务账号（Service Account）OAuth 2.0 认证转换为通用的 OpenAI API Key 鉴权模式，下游客户端（如 Cursor、NextChat、Cherry Studio、OpenAI SDK 等）只需配置标准的 `Base URL` 和静态 `API Key`，即可无缝调用 Vertex AI 模型。
+
+---
+
+## 快速上手
+
+### 方式 A：通过 PyPI 全局安装（推荐）
+
+本工具已正式发布至 PyPI，支持通过 `uv tool`、`uvx` 或 `pip` 全局安装与运行：
+
+```powershell
+# 1. 全局安装 CLI 工具（推荐使用 uv）
+uv tool install vertext-ai-proxy
+
+# 或者使用 pip 全局安装：
+# pip install vertext-ai-proxy
+
+# 2. 在任意工作目录下一键初始化配置文件
+vap init
+
+# 3. 按提示编辑当前目录下的 config.local.yaml：
+#    - 设置您的自定义 API Key (例如 sk-my-secret-token)
+#    - 将 GCP 服务账号 service_account.json 放在该目录（或配置绝对路径）
+
+# 4. 启动反向代理服务
+vap run
+```
+
+> [!TIP]
+> **免安装运行（uvx）**：如果您不想全局安装，也可以通过 `uvx` 直接执行：
+> ```powershell
+> uvx vertext-ai-proxy vap init
+> uvx vertext-ai-proxy vap run
+> ```
+> **版本升级**：
+> ```powershell
+> uv tool upgrade vertext-ai-proxy
+> # 或 pip install --upgrade vertext-ai-proxy
+> ```
+
+支持的 CLI 参数：
+- `vap init [-f/--force]`：在当前目录创建 `config.local.yaml`（带防误覆盖保护）。
+- `vap run [-c/--config <path>] [-H/--host <host>] [-p/--port <port>]`：启动服务。
+- `vap -v/--version`：查看当前工具版本。
+
+---
+
+### 方式 B：源码本地开发运行
+
+#### 1. 放置 GCP 服务账号密钥
+
+从 Google Cloud 控制台下载服务账号密钥 JSON，重命名为 `service_account.json` 放置在项目根目录：
+
+```text
+Vertext-AI-Proxy/
+├── service_account.json    <-- 放置在此
+├── config.example.yaml
+└── ...
+```
+
+### 2. 创建私有配置文件
+
+复制示例配置文件为私有覆盖配置 `config.local.yaml`（此文件已被 `.gitignore` 自动忽略）：
+
+```powershell
+Copy-Item config.example.yaml config.local.yaml
+```
+
+打开 `config.local.yaml`，**将示例 Key 修改为您自己的私密 Key**：
+
+```yaml
+server:
+  host: "127.0.0.1"    # 默认仅允许本地访问
+  port: 8766           # 默认端口
+
+proxy:
+  api_keys:
+    - "sk-my-secret-token-123456"   # ⚠️ 请修改为您自己的密码，勿使用示例 Key
+
+  auto_prefix_model: true
+
+  # 可选：如果在国内需要配置代理访问 Google，取消注释并填入代理端口：
+  # http_proxy: "http://127.0.0.1:7890"
+
+gcp:
+  service_account_file: "service_account.json"
+  project_id: ""       # 留空将自动从 service_account.json 读取
+  location: "global"   # 推荐 global 或对应部署区域
+```
+
+### 3. 启动服务
+
+使用 `uv` 启动服务：
+
+```powershell
+$env:PYTHONUTF8=1; uv run python -m vertext_ai_proxy.app
+```
+
+启动成功后，终端将输出类似如下信息：
+```text
+INFO:     Started server process
+INFO:     Waiting for application startup.
+INFO:     Vertex AI OpenAI Proxy started on http://127.0.0.1:8766 (GCP Project: your-project-id, Location: global)
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://127.0.0.1:8766 (Press CTRL+C to quit)
+```
+
+---
+
+## 核心特性
+
+- **协议原生兼容**：直接对接 Google 官方 `endpoints/openapi`，无需进行复杂的数据结构重写与字段转换。
+- **全能向量生成（Embeddings）**：提供标准 OpenAI `/v1/embeddings` 端点，透明桥接 Google Vertex AI 原生预测能力，原生支持 `text-embedding-004`、`gemini-embedding-001` 和 `text-multilingual-embedding-002`，支持自定义向量维度与批量生成。
+- **自动化 Token 管理**：读取 `service_account.json` 自动解析 `project_id`，在内存中管理并自动异步续签 Google OAuth Bearer Token（有效时长 1 小时，过期前 5 分钟自动刷新）。
+- **零缓冲流式输出**：基于 `httpx` 实现 Server-Sent Events（SSE）无缓冲实时打字机输出，长文本生成更稳定。
+- **安全优先（Secure by Default）**：
+  - 默认仅监听本地回环地址（`127.0.0.1:8766`），杜绝局域网或公网非预期暴露。
+  - **启动期强校验**：启动时检测到示例/占位 Key（如 `sk-change-this-...`）或空 Key 时，立即终止运行并报错提示。
+  - `.gitignore` 默认严格忽略 `config.local.yaml` 与 `service_account.json`。
+- **模型名智能兼容**：客户端请求 `gemini-2.5-flash` 时，代理可自动重写为 `google/gemini-2.5-flash`。
+- **多 Key 与网络代理**：支持多客户端 API Key 白名单配置，支持配置本地网络代理端口（`http_proxy`）。
+
+---
+
+## 客户端接入方式
+
+### 1. Cursor / NextChat / Cherry Studio 配置
+
+- **API 接口地址（Base URL）**：`http://127.0.0.1:8766/v1`
+- **API Key**：您在 `config.local.yaml` 中设置的 Key（如 `sk-my-secret-token-123456`）
+- **模型名称**：`gemini-2.5-flash`、`gemini-2.5-pro`、`gemini-1.5-pro`（代理会自动补全 `google/` 前缀）
+
+### 2. Python OpenAI SDK
+
+```python
+import openai
+
+client = openai.OpenAI(
+    base_url="http://127.0.0.1:8766/v1",
+    api_key="sk-my-secret-token-123456",
+)
+
+response = client.chat.completions.create(
+    model="gemini-2.5-flash",
+    messages=[
+        {"role": "user", "content": "你好，请做个自我介绍！"},
+    ],
+    stream=True,
+)
+
+for chunk in response:
+    content = chunk.choices[0].delta.content or ""
+    print(content, end="", flush=True)
+```
+
+### 3. Python OpenAI SDK 生成文本向量 (Embeddings)
+
+```python
+import openai
+
+client = openai.OpenAI(
+    base_url="http://127.0.0.1:8766/v1",
+    api_key="sk-my-secret-token-123456",
+)
+
+# 1. 单文本嵌入
+embedding_res = client.embeddings.create(
+    model="text-embedding-004",
+    input="The quick brown fox jumps over the lazy dog",
+)
+print("Vector dims:", len(embedding_res.data[0].embedding))
+
+# 2. 多文本批量嵌入并自定义维度
+batch_res = client.embeddings.create(
+    model="gemini-embedding-001",
+    input=["First document", "Second document"],
+    dimensions=512,
+)
+print(f"Batch count: {len(batch_res.data)}, Dims: {len(batch_res.data[0].embedding)}")
+```
+
+### 4. cURL 命令行测试
+
+```bash
+curl http://127.0.0.1:8766/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer sk-my-secret-token-123456" \
+  -d '{
+    "model": "gemini-2.5-flash",
+    "messages": [{"role": "user", "content": "Hello!"}]
+  }'
+```
+

vertext_ai_proxy-0.2.1/README.md

@@ -0,0 +1,201 @@
+# Vertex AI OpenAI Proxy
+
+[![PyPI version](https://img.shields.io/pypi/v/vertext-ai-proxy.svg)](https://pypi.org/project/vertext-ai-proxy/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://pypi.org/project/vertext-ai-proxy/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+轻量级 Google Cloud Vertex AI（Gemini Enterprise Agent Platform）OpenAI 协议反向代理网关。
+
+将 Google Cloud 的服务账号（Service Account）OAuth 2.0 认证转换为通用的 OpenAI API Key 鉴权模式，下游客户端（如 Cursor、NextChat、Cherry Studio、OpenAI SDK 等）只需配置标准的 `Base URL` 和静态 `API Key`，即可无缝调用 Vertex AI 模型。
+
+---
+
+## 快速上手
+
+### 方式 A：通过 PyPI 全局安装（推荐）
+
+本工具已正式发布至 PyPI，支持通过 `uv tool`、`uvx` 或 `pip` 全局安装与运行：
+
+```powershell
+# 1. 全局安装 CLI 工具（推荐使用 uv）
+uv tool install vertext-ai-proxy
+
+# 或者使用 pip 全局安装：
+# pip install vertext-ai-proxy
+
+# 2. 在任意工作目录下一键初始化配置文件
+vap init
+
+# 3. 按提示编辑当前目录下的 config.local.yaml：
+#    - 设置您的自定义 API Key (例如 sk-my-secret-token)
+#    - 将 GCP 服务账号 service_account.json 放在该目录（或配置绝对路径）
+
+# 4. 启动反向代理服务
+vap run
+```
+
+> [!TIP]
+> **免安装运行（uvx）**：如果您不想全局安装，也可以通过 `uvx` 直接执行：
+> ```powershell
+> uvx vertext-ai-proxy vap init
+> uvx vertext-ai-proxy vap run
+> ```
+> **版本升级**：
+> ```powershell
+> uv tool upgrade vertext-ai-proxy
+> # 或 pip install --upgrade vertext-ai-proxy
+> ```
+
+支持的 CLI 参数：
+- `vap init [-f/--force]`：在当前目录创建 `config.local.yaml`（带防误覆盖保护）。
+- `vap run [-c/--config <path>] [-H/--host <host>] [-p/--port <port>]`：启动服务。
+- `vap -v/--version`：查看当前工具版本。
+
+---
+
+### 方式 B：源码本地开发运行
+
+#### 1. 放置 GCP 服务账号密钥
+
+从 Google Cloud 控制台下载服务账号密钥 JSON，重命名为 `service_account.json` 放置在项目根目录：
+
+```text
+Vertext-AI-Proxy/
+├── service_account.json    <-- 放置在此
+├── config.example.yaml
+└── ...
+```
+
+### 2. 创建私有配置文件
+
+复制示例配置文件为私有覆盖配置 `config.local.yaml`（此文件已被 `.gitignore` 自动忽略）：
+
+```powershell
+Copy-Item config.example.yaml config.local.yaml
+```
+
+打开 `config.local.yaml`，**将示例 Key 修改为您自己的私密 Key**：
+
+```yaml
+server:
+  host: "127.0.0.1"    # 默认仅允许本地访问
+  port: 8766           # 默认端口
+
+proxy:
+  api_keys:
+    - "sk-my-secret-token-123456"   # ⚠️ 请修改为您自己的密码，勿使用示例 Key
+
+  auto_prefix_model: true
+
+  # 可选：如果在国内需要配置代理访问 Google，取消注释并填入代理端口：
+  # http_proxy: "http://127.0.0.1:7890"
+
+gcp:
+  service_account_file: "service_account.json"
+  project_id: ""       # 留空将自动从 service_account.json 读取
+  location: "global"   # 推荐 global 或对应部署区域
+```
+
+### 3. 启动服务
+
+使用 `uv` 启动服务：
+
+```powershell
+$env:PYTHONUTF8=1; uv run python -m vertext_ai_proxy.app
+```
+
+启动成功后，终端将输出类似如下信息：
+```text
+INFO:     Started server process
+INFO:     Waiting for application startup.
+INFO:     Vertex AI OpenAI Proxy started on http://127.0.0.1:8766 (GCP Project: your-project-id, Location: global)
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://127.0.0.1:8766 (Press CTRL+C to quit)
+```
+
+---
+
+## 核心特性
+
+- **协议原生兼容**：直接对接 Google 官方 `endpoints/openapi`，无需进行复杂的数据结构重写与字段转换。
+- **全能向量生成（Embeddings）**：提供标准 OpenAI `/v1/embeddings` 端点，透明桥接 Google Vertex AI 原生预测能力，原生支持 `text-embedding-004`、`gemini-embedding-001` 和 `text-multilingual-embedding-002`，支持自定义向量维度与批量生成。
+- **自动化 Token 管理**：读取 `service_account.json` 自动解析 `project_id`，在内存中管理并自动异步续签 Google OAuth Bearer Token（有效时长 1 小时，过期前 5 分钟自动刷新）。
+- **零缓冲流式输出**：基于 `httpx` 实现 Server-Sent Events（SSE）无缓冲实时打字机输出，长文本生成更稳定。
+- **安全优先（Secure by Default）**：
+  - 默认仅监听本地回环地址（`127.0.0.1:8766`），杜绝局域网或公网非预期暴露。
+  - **启动期强校验**：启动时检测到示例/占位 Key（如 `sk-change-this-...`）或空 Key 时，立即终止运行并报错提示。
+  - `.gitignore` 默认严格忽略 `config.local.yaml` 与 `service_account.json`。
+- **模型名智能兼容**：客户端请求 `gemini-2.5-flash` 时，代理可自动重写为 `google/gemini-2.5-flash`。
+- **多 Key 与网络代理**：支持多客户端 API Key 白名单配置，支持配置本地网络代理端口（`http_proxy`）。
+
+---
+
+## 客户端接入方式
+
+### 1. Cursor / NextChat / Cherry Studio 配置
+
+- **API 接口地址（Base URL）**：`http://127.0.0.1:8766/v1`
+- **API Key**：您在 `config.local.yaml` 中设置的 Key（如 `sk-my-secret-token-123456`）
+- **模型名称**：`gemini-2.5-flash`、`gemini-2.5-pro`、`gemini-1.5-pro`（代理会自动补全 `google/` 前缀）
+
+### 2. Python OpenAI SDK
+
+```python
+import openai
+
+client = openai.OpenAI(
+    base_url="http://127.0.0.1:8766/v1",
+    api_key="sk-my-secret-token-123456",
+)
+
+response = client.chat.completions.create(
+    model="gemini-2.5-flash",
+    messages=[
+        {"role": "user", "content": "你好，请做个自我介绍！"},
+    ],
+    stream=True,
+)
+
+for chunk in response:
+    content = chunk.choices[0].delta.content or ""
+    print(content, end="", flush=True)
+```
+
+### 3. Python OpenAI SDK 生成文本向量 (Embeddings)
+
+```python
+import openai
+
+client = openai.OpenAI(
+    base_url="http://127.0.0.1:8766/v1",
+    api_key="sk-my-secret-token-123456",
+)
+
+# 1. 单文本嵌入
+embedding_res = client.embeddings.create(
+    model="text-embedding-004",
+    input="The quick brown fox jumps over the lazy dog",
+)
+print("Vector dims:", len(embedding_res.data[0].embedding))
+
+# 2. 多文本批量嵌入并自定义维度
+batch_res = client.embeddings.create(
+    model="gemini-embedding-001",
+    input=["First document", "Second document"],
+    dimensions=512,
+)
+print(f"Batch count: {len(batch_res.data)}, Dims: {len(batch_res.data[0].embedding)}")
+```
+
+### 4. cURL 命令行测试
+
+```bash
+curl http://127.0.0.1:8766/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer sk-my-secret-token-123456" \
+  -d '{
+    "model": "gemini-2.5-flash",
+    "messages": [{"role": "user", "content": "Hello!"}]
+  }'
+```
+

vertext_ai_proxy-0.2.1/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "vertext-ai-proxy"
+version = "0.2.1"
+description = "轻量级 Google Cloud Vertex AI（Gemini Enterprise Agent Platform）OpenAI 协议反向代理网关"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+keywords = [
+    "vertex-ai",
+    "gemini",
+    "openai",
+    "reverse-proxy",
+    "llm",
+    "embeddings",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "fastapi>=0.162.0",
+    "google-auth>=2.62.0",
+    "httpx>=0.28.1",
+    "pydantic>=2.14.1",
+    "pyyaml>=6.0.3",
+    "requests>=2.34.2",
+    "uvicorn>=0.54.0",
+]
+
+[[project.authors]]
+name = "entr0pia"
+email = "30486766+entr0pia@users.noreply.github.com"
+
+[project.urls]
+Homepage = "https://github.com/entr0pia/vertext-ai-proxy"
+Repository = "https://github.com/entr0pia/vertext-ai-proxy"
+Issues = "https://github.com/entr0pia/vertext-ai-proxy/issues"
+
+[project.scripts]
+vap = "vertext_ai_proxy.cli:main"
+vertext-ai-proxy = "vertext_ai_proxy.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.1",
+]

vertext_ai_proxy-0.2.1/pyproject.toml.orig

@@ -0,0 +1,43 @@
+[project]
+name = "vertext-ai-proxy"
+version = "0.2.1"
+description = "轻量级 Google Cloud Vertex AI（Gemini Enterprise Agent Platform）OpenAI 协议反向代理网关"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "entr0pia", email = "30486766+entr0pia@users.noreply.github.com" },
+]
+requires-python = ">=3.11"
+keywords = ["vertex-ai", "gemini", "openai", "reverse-proxy", "llm", "embeddings"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "fastapi>=0.162.0",
+    "google-auth>=2.62.0",
+    "httpx>=0.28.1",
+    "pydantic>=2.14.1",
+    "pyyaml>=6.0.3",
+    "requests>=2.34.2",
+    "uvicorn>=0.54.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/entr0pia/vertext-ai-proxy"
+Repository = "https://github.com/entr0pia/vertext-ai-proxy"
+Issues = "https://github.com/entr0pia/vertext-ai-proxy/issues"
+
+[project.scripts]
+vap = "vertext_ai_proxy.cli:main"
+vertext-ai-proxy = "vertext_ai_proxy.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.13.5,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1", "pytest-asyncio>=1.4.1"]

vertext_ai_proxy-0.2.1/src/vertext_ai_proxy/__init__.py

@@ -0,0 +1,4 @@
+from vertext_ai_proxy._version import __version__
+from vertext_ai_proxy.cli import main
+
+__all__ = ["main", "__version__"]

vertext_ai_proxy-0.2.1/src/vertext_ai_proxy/_version.py

@@ -0,0 +1,16 @@
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+import re
+
+try:
+    __version__ = version("vertext-ai-proxy")
+except PackageNotFoundError:
+    try:
+        pyproject_path = Path(__file__).resolve().parents[2] / "pyproject.toml"
+        if pyproject_path.is_file():
+            match = re.search(r'version\s*=\s*["\']([^"\']+)["\']', pyproject_path.read_text(encoding="utf-8"))
+            __version__ = match.group(1) if match else "0.0.0.dev0"
+        else:
+            __version__ = "0.0.0.dev0"
+    except Exception:
+        __version__ = "0.0.0.dev0"

vertext_ai_proxy-0.2.1/src/vertext_ai_proxy/app.py

@@ -0,0 +1,144 @@
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+import logging
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+import httpx
+import uvicorn
+
+from vertext_ai_proxy.core.auth import GCPTokenManager
+from vertext_ai_proxy._version import __version__
+from vertext_ai_proxy.core.config import AppConfig, load_config, validate_config
+from vertext_ai_proxy.core.exceptions import (
+    OpenAIAPIException,
+    openai_exception_handler,
+)
+from vertext_ai_proxy.core.security import APIKeyValidator
+from vertext_ai_proxy.proxy import VertexAIProxy
+from vertext_ai_proxy.routers.health import router as health_router
+from vertext_ai_proxy.routers.v1.chat import router as chat_router
+from vertext_ai_proxy.routers.v1.embeddings import router as embeddings_router
+from vertext_ai_proxy.routers.v1.models import router as models_router
+
+logger = logging.getLogger(__name__)
+
+
+def create_app(
+    config: AppConfig | None = None,
+    token_manager: GCPTokenManager | None = None,
+    http_client: httpx.AsyncClient | None = None,
+) -> FastAPI:
+    """FastAPI 应用工厂函数，支持依赖注入以便利单元测试。"""
+    active_config = config or load_config()
+
+    # 启动前强制执行配置安全校验（阻断示例占位 Key 和空 Key）
+    validate_config(active_config)
+
+    # 初始化 Token 管理器
+    active_token_manager = token_manager or GCPTokenManager(active_config.gcp)
+
+    created_client = False
+    effective_http_client = http_client
+    if effective_http_client is None:
+        proxy_url = active_config.proxy.http_proxy
+        effective_http_client = httpx.AsyncClient(
+            proxy=proxy_url if proxy_url else None,
+            follow_redirects=True,
+        )
+        created_client = True
+
+    proxy_instance = VertexAIProxy(
+        config=active_config,
+        token_manager=active_token_manager,
+        http_client=effective_http_client,
+    )
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+        logger.info(
+            f"Vertex AI OpenAI Proxy started on http://{active_config.server.host}:{active_config.server.port} "
+            f"(GCP Project: {active_token_manager.project_id}, Location: {active_token_manager.location})"
+        )
+        try:
+            yield
+        finally:
+            if created_client and effective_http_client:
+                await effective_http_client.aclose()
+                logger.info("HTTP client closed.")
+
+    app = FastAPI(
+        title="Vertex AI OpenAI Proxy",
+        description="Lightweight reverse proxy translating Google Cloud Vertex AI OpenAPI to OpenAI format",
+        version=__version__,
+        lifespan=lifespan,
+    )
+
+    # 注册依赖服务与组件至 app.state
+    app.state.config = active_config
+    app.state.proxy = proxy_instance
+    app.state.client = proxy_instance.client
+    app.state.chat_service = proxy_instance.chat_service
+    app.state.embedding_service = proxy_instance.embedding_service
+    app.state.model_service = proxy_instance.model_service
+    app.state.api_key_validator = APIKeyValidator(active_config)
+
+    # 注册符合 OpenAI 标准的异常拦截器
+    app.add_exception_handler(OpenAIAPIException, openai_exception_handler)
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_exception_handler(
+        request: Request, exc: RequestValidationError
+    ) -> JSONResponse:
+        errors = exc.errors()
+        err_msg = "; ".join([f"{err.get('loc', [])}: {err.get('msg')}" for err in errors])
+        return JSONResponse(
+            status_code=400,
+            content={
+                "error": {
+                    "message": err_msg,
+                    "type": "invalid_request_error",
+                    "param": str(errors[0].get("loc", [None])[-1]) if errors else None,
+                    "code": "invalid_parameter",
+                }
+            },
+        )
+
+    @app.exception_handler(Exception)
+    async def generic_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+        logger.exception(f"Unhandled error processing {request.method} {request.url}: {exc}")
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": {
+                    "message": f"Internal proxy error: {str(exc)}",
+                    "type": "api_error",
+                    "param": None,
+                    "code": "internal_error",
+                }
+            },
+        )
+
+    # 挂载模块化路由
+    app.include_router(health_router)
+    app.include_router(models_router)
+    app.include_router(chat_router)
+    app.include_router(embeddings_router)
+
+    return app
+
+
+def main() -> None:
+    """服务主入口命令行。"""
+    config = load_config()
+    app = create_app(config=config)
+    uvicorn.run(
+        app,
+        host=config.server.host,
+        port=config.server.port,
+        log_level=config.server.log_level.lower(),
+    )
+
+
+if __name__ == "__main__":
+    main()