Skip to content

Commit cbfcbc5

Browse files
Xichun123Xichun123
committed
docs(vertex): document GCP and GCS deployment
1 parent 242008b commit cbfcbc5

2 files changed

Lines changed: 202 additions & 26 deletions

File tree

‎README.en.md‎

Lines changed: 101 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -243,19 +243,29 @@ Notes:
243243
244244
### Runtime Configuration and Environment Variables
245245

246-
| Variable | Purpose | Public | Docker default |
247-
| :------------------------------ | :----------------------------------------------------------------------------------------------- | :-------------------- | :------------------------------------------ |
248-
| `GEMINI_API_KEY` | Optional server-managed Gemini API key; when set, it takes precedence over browser settings keys | Server only | Empty |
249-
| `PORT` | Port used by the API service | Server only | `3001` |
250-
| `GEMINI_API_BASE` | Upstream Gemini API base URL | Server only | `https://generativelanguage.googleapis.com` |
251-
| `ALLOWED_ORIGINS` | Comma-separated CORS allowlist for cross-origin deployments | Server only | Empty |
252-
| `ENABLE_MCP_STDIO` | Enables `stdio` MCP server calls | Server only | `false` |
253-
| `ENABLE_MCP_PRIVATE_HTTP` | Allows the API service to call private or local HTTP MCP URLs | Server only | `false` |
254-
| `RUNTIME_SERVER_MANAGED_API` | Enables server-managed API mode by default in the frontend | Public runtime config | `false` |
255-
| `RUNTIME_USE_CUSTOM_API_CONFIG` | Enables custom API configuration by default | Public runtime config | `true` |
256-
| `RUNTIME_USE_API_PROXY` | Enables API proxy mode by default | Public runtime config | `true` |
257-
| `RUNTIME_API_PROXY_URL` | Default Gemini proxy URL for the frontend | Public runtime config | `/api/gemini` |
258-
| `RUNTIME_PYODIDE_BASE_URL` | Optional Pyodide runtime asset URL; when blank, same-origin `/pyodide/` is used | Public runtime config | Empty |
246+
| Variable | Purpose | Public | Docker default |
247+
| :----------------------------------- | :------------------------------------------------------------------------------ | :-------------------- | :------------------------------------------ |
248+
| `GEMINI_API_KEY` | Optional server-managed Gemini API key for AI Studio mode | Server only | Empty |
249+
| `PORT` | Port used by the API service | Server only | `3001` |
250+
| `GEMINI_API_BASE` | AI Studio upstream API base URL | Server only | `https://generativelanguage.googleapis.com` |
251+
| `GEMINI_BACKEND` | Upstream backend: `aistudio` or `vertex` | Server only | `aistudio` |
252+
| `GCP_PROJECT_ID` | Google Cloud project used by Vertex AI | Server only | Empty |
253+
| `GCP_LOCATION` | Vertex AI location, such as `global` or `us-central1` | Server only | `us-central1` |
254+
| `GOOGLE_APPLICATION_CREDENTIALS_DIR` | Host directory mounted at `/run/secrets`; use `./secrets` only for Vertex mode | Docker host config | `./docker/empty-secrets` |
255+
| `GOOGLE_APPLICATION_CREDENTIALS` | Service Account JSON path inside the API container | Server only | Empty |
256+
| `GCS_BUCKET` | Optional GCS bucket backing Gemini Files API requests in Vertex mode | Server only | Empty |
257+
| `GCS_OBJECT_PREFIX` | Object prefix used for uploaded files | Server only | `amc-files/` |
258+
| `GCS_MAX_FILE_BYTES` | Maximum file size accepted by the GCS adapter | Server only | `2147483648` |
259+
| `ALLOWED_ORIGINS` | Comma-separated CORS allowlist for cross-origin deployments | Server only | Empty |
260+
| `ENABLE_MCP_STDIO` | Enables `stdio` MCP server calls | Server only | `false` |
261+
| `ENABLE_MCP_PRIVATE_HTTP` | Allows the API service to call private or local HTTP MCP URLs | Server only | `false` |
262+
| `RUNTIME_SERVER_MANAGED_API` | Enables server-managed API mode by default in the frontend | Public runtime config | `false` |
263+
| `RUNTIME_USE_CUSTOM_API_CONFIG` | Enables custom API configuration by default | Public runtime config | `true` |
264+
| `RUNTIME_USE_API_PROXY` | Enables API proxy mode by default | Public runtime config | `true` |
265+
| `RUNTIME_API_PROXY_URL` | Default Gemini proxy URL for the frontend | Public runtime config | `/api/gemini` |
266+
| `RUNTIME_PYODIDE_BASE_URL` | Optional Pyodide runtime asset URL; when blank, same-origin `/pyodide/` is used | Public runtime config | Empty |
267+
| `RUNTIME_BACKEND_FLAVOR` | Frontend backend behavior: `aistudio` or `vertex` | Public runtime config | `aistudio` |
268+
| `RUNTIME_ENFORCE_API_CONFIG` | Makes runtime API routing override stale browser settings | Public runtime config | `false` |
259269

260270
The `RUNTIME_*` values are written into `runtime-config.js` at container startup and are readable by the browser. Only put public configuration there. The public/runtime-config.js template is used for static builds and keeps custom API configuration and proxy mode disabled by default; Docker overwrites it through `docker/web-server.js` at container startup using the defaults above.
261271

@@ -269,6 +279,84 @@ If you want server-managed credentials for regular Gemini requests, set `GEMINI_
269279

270280
OpenAI Compatible mode currently does not read `RUNTIME_API_PROXY_URL`, `RUNTIME_USE_API_PROXY`, or `RUNTIME_SERVER_MANAGED_API`. It sends `chat/completions` requests directly to the OpenAI-compatible Base URL configured in Settings, using its separate key set. If you want that mode to pass through your own gateway, point the Base URL at that gateway directly.
271281

282+
#### Switching backend profiles
283+
284+
The repository includes three Docker environment examples:
285+
286+
```text
287+
.env.vertex.example
288+
.env.aistudio.example
289+
.env.byok.example
290+
```
291+
292+
Create private local copies and fill in only the required secrets:
293+
294+
```bash
295+
cp .env.vertex.example .env.vertex.local
296+
cp .env.aistudio.example .env.aistudio.local
297+
cp .env.byok.example .env.byok.local
298+
```
299+
300+
The `.local` files are ignored by Git. Switch modes without rebuilding images:
301+
302+
```bash
303+
npm run backend:switch -- vertex
304+
npm run backend:switch -- aistudio
305+
npm run backend:switch -- byok
306+
```
307+
308+
- `vertex` uses the Service Account under `GOOGLE_APPLICATION_CREDENTIALS_DIR` and server-managed Vertex authentication.
309+
- `aistudio` requires `GEMINI_API_KEY` in `.env.aistudio.local`; the browser does not receive that key.
310+
- `byok` requires `GEMINI_API_KEY` to remain empty; enter the key in the browser settings instead.
311+
312+
The switch command validates the selected profile, recreates the containers, and waits for `/health`. Refresh every open AMC WebUI tab after switching; accept the in-app update prompt or use a hard reload when a new frontend image was built. All three profiles set `RUNTIME_ENFORCE_API_CONFIG=true`, so stale IndexedDB settings cannot keep the previous credential mode active after reload. AI Studio and BYOK profiles mount `./docker/empty-secrets` instead of the real Service Account directory.
313+
314+
#### Vertex AI and GCS
315+
316+
Vertex mode authenticates in the API service with Google Application Default Credentials, rewrites Gemini model requests to Vertex AI publisher endpoints, and removes the browser API-key requirement. To use it with Docker Compose:
317+
318+
```env
319+
GEMINI_BACKEND=vertex
320+
GCP_PROJECT_ID=your-gcp-project-id
321+
GCP_LOCATION=global
322+
GOOGLE_APPLICATION_CREDENTIALS_DIR=./secrets
323+
GOOGLE_APPLICATION_CREDENTIALS=/run/secrets/sa.json
324+
325+
# Optional: enables Gemini Files API compatibility through GCS.
326+
GCS_BUCKET=your-gcs-bucket
327+
GCS_OBJECT_PREFIX=amc-files/
328+
GCS_MAX_FILE_BYTES=2147483648
329+
330+
RUNTIME_BACKEND_FLAVOR=vertex
331+
RUNTIME_ENFORCE_API_CONFIG=true
332+
RUNTIME_API_PROXY_URL=/api/gemini
333+
```
334+
335+
1. Put the Service Account JSON at `./secrets/sa.json` and set `GOOGLE_APPLICATION_CREDENTIALS_DIR=./secrets`. Docker Compose mounts that directory read-only at `/run/secrets`.
336+
2. Grant the Service Account `roles/aiplatform.user`. If `GCS_BUCKET` is configured, also grant `roles/storage.objectUser` on that bucket.
337+
3. To create/configure the bucket, run:
338+
339+
```bash
340+
GCP_PROJECT_ID=... GCS_BUCKET=... GCS_LOCATION=us-central1 VERTEX_SA_EMAIL=... \
341+
bash scripts/setup-gcs-bucket.sh
342+
```
343+
344+
When `RUNTIME_BACKEND_FLAVOR=vertex`, the frontend enforces server-managed `/api/gemini` routing even if the browser has stale AI Studio settings. The optional GCS adapter accepts the existing resumable Files API flow, writes uploads under `gs://<bucket>/<prefix>`, and rewrites file references before forwarding model requests. Frontend chunks are 8 MB; the API rejects buffered chunks over 50 MB and enforces `GCS_MAX_FILE_BYTES` per file.
345+
346+
Vertex mode covers HTTP model requests and the GCS-backed Files adapter. Live API still connects directly from the browser and requires a browser-available Gemini API key; it is not proxied through Vertex mode.
347+
348+
After the containers are running, a real-project smoke test is available:
349+
350+
```bash
351+
GCP_PROJECT_ID=... \
352+
GCS_BUCKET=... \
353+
GOOGLE_APPLICATION_CREDENTIALS=./secrets/sa.json \
354+
SKIP_IMAGEN=1 \
355+
npm run verify:vertex-e2e
356+
```
357+
358+
Remove `SKIP_IMAGEN=1` to include an Imagen request. If `WEB_PORT` is not `8080`, set `API_BASE_URL=http://localhost:<port>`. The script verifies health, text generation, resumable upload, the GCS object, metadata refresh, multimodal generation, and optional Imagen generation, then deletes its test object unless `NO_CLEANUP=1` is set.
359+
272360
### Option 3: Cloudflare Pages + Standalone API
273361

274362
You can deploy the frontend to Cloudflare Pages and run `server/` as a separate Node service on a VM, container platform, or serverless container runtime.

0 commit comments

Comments
 (0)