docs: add the Gemini/Vertex AI setup guide
Written from an actual first-time setup on a second machine, in order, including every wall that was hit and the exact click-path past it: the two authentication methods, the two separate (legacy + managed) organization policies that can block service account key creation, the Vertex AI User role requirement, and a troubleshooting table mapping each literal error message we saw to its real cause. Leads with the one fact that caused most of the confusion: none of this setup travels with git pull. Every machine running MaskanX needs it done locally, once, even with identical code. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
AFFAANh
@@ -0,0 +1,196 @@
|
||||
# Setting up Gemini (Google) as a model provider
|
||||
|
||||
This covers Settings → Models → **Gemini (Google)** in MaskanX: both ways to
|
||||
connect it, every wall we actually hit setting it up the first time, and
|
||||
the exact click-path past each one. If you're configuring a new computer
|
||||
and something fails, search this document for the error message you're
|
||||
seeing — it's almost certainly here, worded exactly as Google shows it.
|
||||
|
||||
## The one thing to understand before anything else
|
||||
|
||||
**Nothing about this setup travels with `git pull`.** Not the API key, not
|
||||
the Google Cloud Project ID, not a `gcloud` login, not a service account
|
||||
file. All of it lives only on the computer where you entered it. Two
|
||||
machines running identical MaskanX code can behave completely differently
|
||||
because one of them was never individually configured — that isn't a bug,
|
||||
it's how credentials are supposed to work (the alternative is secrets
|
||||
sitting in git, which is worse). **Every computer that runs MaskanX needs
|
||||
this setup done on it, once, by itself.**
|
||||
|
||||
---
|
||||
|
||||
## Which of the two ways do you need?
|
||||
|
||||
| | Plain API key | Google Cloud Vertex AI |
|
||||
|---|---|---|
|
||||
| Good for | Just using Gemini, nothing else | Billing through Google Cloud, enterprise setups, Gemini image generation |
|
||||
| Setup effort | One box, one paste | Several steps, described below |
|
||||
| Where the key comes from | [aistudio.google.com](https://aistudio.google.com/apikey) | A Google Cloud Project |
|
||||
|
||||
**If you just want Gemini working and don't care about Google Cloud
|
||||
billing:** get a key from Google AI Studio, paste it into the **API Key**
|
||||
box in the Configure Gemini dialog, leave **"Use Vertex AI billing"**
|
||||
switched off, and you're done. Skip the rest of this document.
|
||||
|
||||
**If you need Vertex AI** (the switch is on), keep reading — this is the
|
||||
path with all the gotchas.
|
||||
|
||||
---
|
||||
|
||||
## Part 1 — Vertex AI setup
|
||||
|
||||
### 1.1 Find your Google Cloud Project ID
|
||||
|
||||
Go to [console.cloud.google.com](https://console.cloud.google.com). Click
|
||||
the project name at the top-left. The **ID** shown under the display name
|
||||
(not the display name itself — a project's *name* and *ID* are different
|
||||
things, and the name is often the unhelpful default "My First Project")
|
||||
is what goes in the **Google Cloud Project ID** field. It looks like
|
||||
`project-b6a838f4-89bb-48f7-841` or a custom slug you chose yourself.
|
||||
|
||||
### 1.2 Vertex Location
|
||||
|
||||
Use `global` unless you specifically know your model needs a particular
|
||||
region.
|
||||
|
||||
### 1.3 Authenticate — pick ONE of these two methods
|
||||
|
||||
#### Method A — Local login (recommended for a laptop / local dev)
|
||||
|
||||
No file to handle, nothing to paste. In a terminal on **that specific
|
||||
computer**:
|
||||
|
||||
```
|
||||
gcloud auth application-default login
|
||||
```
|
||||
|
||||
- If the terminal says `gcloud` is not recognized, the Google Cloud CLI
|
||||
isn't installed yet: [cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install),
|
||||
run the installer, then open a **new** terminal window before retrying
|
||||
(the old one won't know the tool exists).
|
||||
- A browser window opens. Sign in with the Google account that owns/has
|
||||
access to the Cloud project. Click Allow.
|
||||
- The terminal prints `Credentials saved to file: ...` — that's success.
|
||||
- Leave the **Service Account JSON** box in MaskanX completely empty.
|
||||
|
||||
This is per-machine. Doing this on one laptop does nothing for another.
|
||||
|
||||
#### Method B — Service Account JSON (for a deployed server, or if `gcloud` isn't available)
|
||||
|
||||
A service account is a robot identity, not your personal Google login.
|
||||
You never hand-type this file — you download it complete from Google
|
||||
Cloud Console.
|
||||
|
||||
1. [console.cloud.google.com/iam-admin/serviceaccounts](https://console.cloud.google.com/iam-admin/serviceaccounts) —
|
||||
confirm the correct project is selected at the top first.
|
||||
2. Use an existing service account if one already exists for this purpose,
|
||||
or **+ CREATE SERVICE ACCOUNT** → give it any name → **Create and
|
||||
Continue** → under "Grant this service account access," add the role
|
||||
**Vertex AI User** → **Continue** → **Done**.
|
||||
3. Click into that service account → **KEYS** tab → **ADD KEY** →
|
||||
**Create new key** → **JSON** → **CREATE**. A file downloads
|
||||
automatically.
|
||||
4. Open the downloaded file in Notepad, select all, copy.
|
||||
5. Paste the **entire file contents**, unedited, into the **Service
|
||||
Account JSON** box in MaskanX.
|
||||
|
||||
A real service account key has about ten fields, including a
|
||||
`private_key` block starting with `-----BEGIN PRIVATE KEY-----`. If what
|
||||
you're pasting doesn't look like that, it isn't a real key — see the
|
||||
troubleshooting table below.
|
||||
|
||||
**Keep this file private.** Anyone who has it can act as that service
|
||||
account in your Cloud project. Don't post it, don't commit it to git.
|
||||
Once it's pasted into MaskanX it's safe to delete the downloaded copy.
|
||||
|
||||
### 1.4 Grant the service account permission (Method B only)
|
||||
|
||||
Even with a valid key, Google will refuse every request until the account
|
||||
is allowed to use Vertex AI:
|
||||
|
||||
1. [console.cloud.google.com/iam-admin/iam](https://console.cloud.google.com/iam-admin/iam)
|
||||
2. **+ GRANT ACCESS** → paste the service account's email (looks like
|
||||
`name@project-number.iam.gserviceaccount.com`) → role **Vertex AI
|
||||
User** → **Save**.
|
||||
3. Changes can take a minute or two to take effect. If it still fails
|
||||
immediately after granting, wait and retry before assuming it's wrong.
|
||||
|
||||
### 1.5 Make sure the Vertex AI API is turned on
|
||||
|
||||
[console.cloud.google.com/apis/library/aiplatform.googleapis.com](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com) —
|
||||
confirm the right project is selected, click **Enable** if it isn't
|
||||
already on.
|
||||
|
||||
---
|
||||
|
||||
## Part 2 — If Google blocks key creation entirely
|
||||
|
||||
Some Google Cloud organizations have a security default that stops
|
||||
*anyone* from creating a service account key, before you even get to pick
|
||||
which service account. If Method B gives you this instead of a download:
|
||||
|
||||
> Service account key creation is disabled
|
||||
> An organisation policy that blocks service accounts key creation has
|
||||
> been enforced on your organisation.
|
||||
|
||||
This is two **separate** locks, not one — Google runs an old version and
|
||||
a new "managed" version of this policy at the same time, and disabling
|
||||
one does not disable the other. Both must be turned off individually if
|
||||
you need Method B (Method A is unaffected by this entirely, which is one
|
||||
more reason to prefer it).
|
||||
|
||||
1. **☰** menu → **IAM & Admin** → **Organization policies**.
|
||||
2. Filter box on that page (not the global search bar at the top of the
|
||||
whole console) → type `service account key`.
|
||||
3. Two rows will match: **"Disable service account key creation"** with
|
||||
constraint ID `iam.disableServiceAccountKeyCreation` (labeled
|
||||
"Managed (legacy)"), and another with the same display name and ID
|
||||
`iam.managed.disableServiceAccountKeyCreation` (labeled "Managed"). You
|
||||
need to fix **both**, separately.
|
||||
4. Click into one → **Manage policy** → select **"Override parent's
|
||||
policy"** → under Rules, select Enforcement **"Off"** → click **Done**
|
||||
to close that box.
|
||||
5. **Then scroll to the very bottom of the page and click "Set policy."**
|
||||
Clicking "Done" alone does *not* save anything — it only closes the
|
||||
rule editor. This exact step is the one everyone misses, twice.
|
||||
6. Confirm the page now shows **Status: Not enforced**.
|
||||
7. Repeat steps 4–6 for the other row (if you're on one, the other one's
|
||||
page usually has a banner offering to jump straight to it).
|
||||
8. Only once *both* show "Not enforced," go back and try creating the key
|
||||
again (Part 1.3, Method B, step 3).
|
||||
|
||||
You need the **Organization Policy Administrator** role to do this. If
|
||||
the "Override parent's policy" option isn't available to click, someone
|
||||
else administers your organization and needs to either do this for you
|
||||
or grant you that role.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting — exact error message → real cause → fix
|
||||
|
||||
| You see | What's actually happening | Fix |
|
||||
|---|---|---|
|
||||
| `Gemini (Google) model does not exist or is not available` | Either the newest model genuinely isn't rolled out to this Cloud project yet (MaskanX automatically tries older ones and should recover on its own), or something else is failing and getting mis-read as this. Check the backend terminal for a line starting `Gemini/Vertex request failed` or `Gemini/Vertex probe:` — it logs Google's real, unfiltered error there. | Read the real error in the terminal, then find it in this table. |
|
||||
| `Your default credentials were not found` | This computer has never authenticated to Google Cloud. This is **not** about the API key, the Project ID, or which model was picked — it fires identically no matter what else is configured correctly. | Part 1.3, Method A (or B). |
|
||||
| `Service account key creation is disabled` | An organization policy is blocking it — see Part 2. | Part 2. |
|
||||
| `Service account info was not in the expected format, missing fields client_email, token_uri` | What was pasted into the Service Account JSON box isn't a real, complete key file — often someone's email and project ID typed in by hand instead. | Download the real file (Part 1.3, Method B) and paste the whole thing, unedited. |
|
||||
| `API key was accepted, but this Google project does not have permission for the requested Gemini API/model` | Authentication succeeded, but the account isn't allowed to use Vertex AI yet. | Part 1.4 — grant the **Vertex AI User** role. |
|
||||
| `API key is invalid or expired` | The key itself (plain API key, or the token behind Vertex auth) is wrong or has been revoked. | Re-check/regenerate the key. |
|
||||
| `currently rate-limited or out of quota` | Real usage limit hit. | Check quota/billing in Cloud Console, or wait. |
|
||||
| `billing is required for this Gemini request` | The Cloud project has no billing account attached. | [console.cloud.google.com/billing](https://console.cloud.google.com/billing) — attach one. |
|
||||
|
||||
---
|
||||
|
||||
## Quick reference
|
||||
|
||||
| Thing | Where to find it |
|
||||
|---|---|
|
||||
| Project ID | Cloud Console → project switcher, top-left → the ID under the display name |
|
||||
| Service account email | IAM & Admin → Service accounts → the "Email" column |
|
||||
| Grant a role | IAM & Admin → IAM → "+ Grant Access" |
|
||||
| Turn on the Vertex AI API | APIs & Services → Library → search "Vertex AI API" |
|
||||
| Org policy list | IAM & Admin → Organization policies |
|
||||
|
||||
If none of this matches what you're seeing, the backend terminal log is
|
||||
the next place to look — every Gemini/Vertex failure now logs the exact,
|
||||
unedited text Google sent back, not just a paraphrase.
|
||||
Reference in New Issue
Block a user