> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inputapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini 原生向量

> 调用原生单条与同步批量向量，验证数量和维度。

当前版本 `30a6d88a4` 的 `controller/relay.go` 用大小写敏感的 `strings.Contains(path, "embed")` 分发原生向量。`:batchEmbedContents` 自身没有小写 `embed`，因此批量调用要求路径模型 ID 含小写 `embed`（例如实际可用的 embedding 模型名）；不含该片段的别名可能进入错误分支。示例在发送前拒绝这类批量别名。此限制来自当前实现，不是 Gemini 协议要求；升级网关后应复核。

原生 Gemini 的单条 `:embedContent` 与同步批量 `:batchEmbedContents` 使用 `content.parts`，返回 `embedding.values` / `embeddings[].values`，与 [OpenAI Embeddings](/zh/guides/embeddings.md) 的 `input` / `data[].embedding` 不同。批量 action 不是异步 Batch API。

按 [REST 运行环境](/zh/guides/http-runtime.md)设置根地址、密钥与不带 `models/` 的裸模型 ID，使用支持 Gemini 原生 embedding 的渠道。

```bash theme={null}
node examples/gemini-embeddings.mjs single
node examples/gemini-embeddings.mjs batch
```

请求中的所有条目使用同一模型。网关将路径模型映射到上游，并重写各条目的 `model`；不要用一次批量请求混合不同模型。当前类型化请求保留 `model`、`content`、`taskType`、`title`、`outputDimensionality`，未知顶层字段不应假定透传。

示例用 `RETRIEVAL_DOCUMENT` 编码文档；查询侧通常选择对应的 `RETRIEVAL_QUERY`。必须由模型支持这些选项；`title` 用于文档检索类型，维度上限及任务类型按具体模型确认。代码验证数量、非空有限数值和同维度后才输出；没有保证向量归一化，也不会跨模型比较。

[单条 API](/zh/api-reference/gemini-embed.md)、[批量 API](/zh/api-reference/gemini-batch-embed.md)。字段语义参考 [Google 原生文档](https://ai.google.dev/api/embeddings)；模型能力和限制需在实际部署验证。

```javascript theme={null}
import { requestJSON } from './http-client.mjs';

try {
  const model = process.env.API_MODEL;
  const mode = process.argv[2] || 'single';
  if (!/^[A-Za-z0-9_-][A-Za-z0-9._-]*$/.test(model || '') || !['single', 'batch'].includes(mode)) {
    throw new Error('Set a bare API_MODEL and use single or batch.');
  }
  // Current gateway dispatch uses a case-sensitive "embed" path check.
  if (mode === 'batch' && !model.includes('embed')) throw new Error('Batch requires an embedding model ID containing lowercase embed on this gateway revision.');
  const texts = mode === 'single' ? ['A guide to API integration.']
    : ['A guide to API integration.', 'A guide to vector retrieval.'];
  const inputs = texts.map((text) => ({
    model: `models/${model}`, content: { parts: [{ text }] }, taskType: 'RETRIEVAL_DOCUMENT',
  }));
  const action = mode === 'single' ? 'embedContent' : 'batchEmbedContents';
  const result = await requestJSON(`/v1beta/models/${encodeURIComponent(model)}:${action}`,
    mode === 'single' ? inputs[0] : { requests: inputs });
  const vectors = mode === 'single' ? [result.embedding] : result.embeddings;
  if (!Array.isArray(vectors) || vectors.length !== texts.length) throw new Error('Missing vectors.');
  let dimensions;
  for (const vector of vectors) {
    const values = vector?.values;
    if (!Array.isArray(values) || !values.length || !values.every((value) => typeof value === 'number' && Number.isFinite(value))
      || (dimensions !== undefined && dimensions !== values.length)) throw new Error('Invalid vector.');
    dimensions = values.length;
  }
  console.log(JSON.stringify({ count: vectors.length, dimensions, vectors: vectors.map((item) => item.values) }));
} catch {
  console.error('Gemini embedding request failed or returned invalid vectors. No automatic retry.');
  process.exitCode = 1;
}
```

[Read in English](/en/guides/gemini-embeddings.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.