记录 Google 赠金接入与检索模型兼容性验收

servers/tools-pve/litellm/README.md

@@ -139,3 +139,50 @@ OAuth 与 Claude cache hit 分别验收，未通过不能写成可用。
 参考：[LiteLLM ChatGPT OAuth](https://docs.litellm.ai/docs/providers/chatgpt)、
 [xAI OAuth 官方源码](https://github.com/BerriAI/litellm/blob/main/litellm/llms/xai/oauth.py)、
 [ZenMux prompt cache](https://zenmux.ai/docs/guide/advanced/prompt-cache.html)。
+
+## Google Agent Platform 与检索模型
+
+2026-10-09 用户确认 Pro 赠金已绑定结算账号后，接入项目
+`gen-lang-client-0312436655`，区域 `global`。复用此前已授权的用户 ADC，
+保存在既有 `tools-litellm-oauth` 卷的 `/tokens/google/adc.json`（0600），
+不进 Git；容器通过 `GOOGLE_APPLICATION_CREDENTIALS` 读取并刷新凭据。
+Arcane Project `.env` 设置 `VERTEXAI_ENABLED=true`、`VERTEXAI_PROJECT`、
+`VERTEXAI_LOCATION`。默认关闭该路线，避免仅有项目名就自动发起付费调用。
+
+| 对外路由 | 实际模型 | 验收 |
+| --- | --- | --- |
+| `gemini-flash-vertex` | `gemini-3.8-flash` | 原生及普通客户端 Chat 均成功 |
+| `gemini-flash-lite-vertex` | `gemini-3.5-flash-lite` | 原生及普通客户端 Chat 均成功 |
+| `gemini-pro-vertex` | `gemini-3.1-pro-preview` | 原生及普通客户端 Chat 均成功 |
+| `gemini-embedding-2-studio` | AI Studio `gemini-embedding-2` | `/v1/embeddings` 两条输入返回两条 1024 维向量，index 正确 |
+
+前三条不冒充 Google 厂商自动 latest 别名；保持与 AI Studio 既有路由分开。
+Google 官方说明 AI Pro 月赠金可用于 Agent Platform，但本次没有从账单
+实证某次请求扣的是赠金；兑换状态由用户确认。赠金耗尽后可能继续产生付费，
+当前没有基于 Google 实时赠金余额的硬停机制，不设置自动跨 provider fallback。
+
+AI Studio 当前账号目录含 `gemini-embedding-001`、`gemini-embedding-2-preview`、
+`gemini-embedding-2`，没有独立 rerank 模型。优先用已经 GA 的 Embedding 2。
+原生 Agent Platform `gemini-embedding-2:embedContent` 已实测返回 1024 维。
+但 LiteLLM 1.104.2 的 `vertex_ai/gemini-embedding-2` 两条输入只返回一条向量，
+故没有开放该代理路由供批量检索使用；不要把 API HTTP 200 当成批量验收。
+
+Google rerank 是 Discovery Engine 的独立 Ranking API，不属于 AI Studio
+embedding 接口。候选 `semantic-ranker-default@latest`、`semantic-ranker-fast@latest`；
+005 为较新模型版本，官方页面 latest 指向说明与表格存在矛盾，不能仅凭别名
+断言实际模型版本。当前项目两条路线均返回 403：Discovery Engine API 未启用。
+尚未启用或纳入 LiteLLM，可到 Google Console 启用 `discoveryengine.googleapis.com`
+后复测中文排序、权限、价格及延迟。当前 LiteLLM 已包含原生 Vertex rerank 适配。
+
+Hindsight 0.10.1 当前生产仍用 unRaid TEI 的 `BAAI/bge-m3` embedding 和
+`Alibaba-NLP/gte-multilingual-reranker-base` rerank，Cohere/rrf 是 fallback。
+该版本原生 Google embedding provider 会把 Vertex Embedding 2 拆成逐条请求，
+并验证输入与输出数量一致，因此后续可优先原生 Google ADC 路线，而非有问题
+的 LiteLLM Vertex embedding 路线。不要直接改生产 provider：即使都选 1024 维，
+BGE 与 Gemini 的向量空间不同，必须重嵌入并重建索引。rerank 切换不要求重建向量。
+embedding 模型禁止使用自动追踪 latest 的别名，否则升级会混用旧向量。
+
+参考：[Google Pro 赠金](https://developers.google.com/program/plans-and-pricing)、
+[Gemini embedding](https://ai.google.dev/gemini-api/docs/embeddings)、
+[Google Ranking API](https://docs.cloud.google.com/generative-ai-app-builder/docs/ranking)、
+[Hindsight 配置](https://hindsight.vectorize.io/developer/configuration)。