Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs: add Gemini embedding provider usage and installation guide (#830)

chethanuk5633394583e0
diff --git a/README.md b/README.md
index 41d6fb7b5..1d6de1ab0 100644
--- a/README.md
+++ b/README.md
@@ -277,7 +277,7 @@ Create a configuration file `~/.openviking/ov.conf`, remove the comments before
}
```
-> **Note**: For embedding models, currently `volcengine` (Doubao), `openai`, and `jina` providers are supported. For VLM models, we support three providers: `volcengine`, `openai`, and `litellm`. The `litellm` provider supports various models including Anthropic (Claude), DeepSeek, Gemini, Moonshot, Zhipu, DashScope, MiniMax, vLLM, Ollama, and more.
+> **Note**: For embedding models, supported providers are `volcengine` (Doubao), `openai`, `jina`, `voyage`, `minimax`, `vikingdb`, and `gemini` (requires `pip install "google-genai>=1.0.0"`). For VLM models, we support three providers: `volcengine`, `openai`, and `litellm`. The `litellm` provider supports various models including Anthropic (Claude), DeepSeek, Gemini, Moonshot, Zhipu, DashScope, MiniMax, vLLM, Ollama, and more.
#### Server Configuration Examples
@@ -351,6 +351,43 @@ Create a configuration file `~/.openviking/ov.conf`, remove the comments before
</details>
+<details>
+<summary><b>Example 3: Using Google Gemini Embedding</b></summary>
+
+Install the required package first:
+
+```bash
+pip install "google-genai>=1.0.0"
+```
+
+```json
+{
+ "storage": {
+ "workspace": "/home/your-name/openviking_workspace"
+ },
+ "embedding": {
+ "dense": {
+ "provider": "gemini",
+ "api_key": "your-google-api-key",
+ "model": "gemini-embedding-2-preview",
+ "dimension": 3072
+ },
+ "max_concurrent": 10
+ },
+ "vlm": {
+ "api_base" : "https://api.openai.com/v1",
+ "api_key" : "your-openai-api-key",
+ "provider" : "openai",
+ "model" : "gpt-4o",
+ "max_concurrent": 100
+ }
+}
+```
+
+Get your Google API key at https://aistudio.google.com/apikey
+
+</details>
+
#### Set Server Configuration Environment Variable
After creating the configuration file, set the environment variable to point to it (Linux/macOS):
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 1328df969..48003e28e 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -115,7 +115,7 @@ Embedding model configuration for vector search, supporting dense, sparse, and h
| Parameter | Type | Description |
|-----------|------|-------------|
| `max_concurrent` | int | Maximum concurrent embedding requests (`embedding.max_concurrent`, default: `10`) |
-| `provider` | str | `"volcengine"`, `"openai"`, `"vikingdb"`, `"jina"`, or `"voyage"` |
+| `provider` | str | `"volcengine"`, `"openai"`, `"vikingdb"`, `"jina"`, `"voyage"`, or `"gemini"` |
| `api_key` | str | API key |
| `model` | str | Model name |
| `dimension` | int | Vector dimension. For Voyage, this maps to `output_dimension` |
@@ -138,6 +138,7 @@ With `input: "multimodal"`, OpenViking can embed text, images (PNG, JPG, etc.),
- `jina`: Jina AI Embedding API
- `voyage`: Voyage AI Embedding API
- `minimax`: MiniMax Embedding API
+- `gemini`: Google Gemini Embedding API (text-only; requires `google-genai>=1.0.0`)
**minimax provider example:**
@@ -227,7 +228,6 @@ Supported Voyage text embedding models include:
If `dimension` is omitted, OpenViking uses the model's default output dimension when creating the vector schema.
-OpenViking currently configures a single dense embedder for both indexing and query-time retrieval, so provider-specific query/document modes are not exposed in config yet.
OpenViking also expects dense float vectors throughout storage and retrieval, so Voyage quantized output dtypes are not exposed in config.
**Local deployment (GGUF/MLX):** Jina embedding models are open-weight and available in GGUF and MLX formats on [Hugging Face](https://huggingface.co/jinaai). You can run them locally with any OpenAI-compatible server (e.g. llama.cpp, MLX, vLLM) and point the `api_base` to your local endpoint:
@@ -246,6 +246,51 @@ OpenViking also expects dense float vectors throughout storage and retrieval, so
}
```
+**gemini provider example:**
+
+> **Note:** Requires `pip install "google-genai>=1.0.0"`. For async batching: `pip install "openviking[gemini-async]"`.
+
+```json
+{
+ "embedding": {
+ "dense": {
+ "provider": "gemini",
+ "api_key": "your-google-api-key",
+ "model": "gemini-embedding-2-preview",
+ "dimension": 3072
+ }
+ }
+}
+```
+
+Available Gemini embedding models:
+- `gemini-embedding-2-preview`: 8192 token input limit, 1–3072 output dimension (MRL)
+- `gemini-embedding-001`: 2048 token input limit, 1–3072 output dimension (MRL)
+- `text-embedding-004`: 2048 token input limit, 768 output dimension (fixed)
+
+Recommended dimensions: `768`, `1536`, or `3072` (default: `3072`).
+
+Get your API key at https://aistudio.google.com/apikey
+
+**Non-symmetric retrieval** (different task types for indexing vs. query):
+
+```json
+{
+ "embedding": {
+ "dense": {
+ "provider": "gemini",
+ "api_key": "your-google-api-key",
+ "model": "gemini-embedding-2-preview",
+ "dimension": 3072,
+ "query_param": "RETRIEVAL_QUERY",
+ "document_param": "RETRIEVAL_DOCUMENT"
+ }
+ }
+}
+```
+
+Supported task types: `RETRIEVAL_QUERY`, `RETRIEVAL_DOCUMENT`, `SEMANTIC_SIMILARITY`, `CLASSIFICATION`, `CLUSTERING`, `CODE_RETRIEVAL_QUERY`, `QUESTION_ANSWERING`, `FACT_VERIFICATION`.
+
#### Sparse Embedding
> **Note:** Volcengine sparse embedding is supported starting from model `doubao-embedding-vision-250615`.
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 588eb9509..a5c3507df 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -121,7 +121,7 @@ OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支
| 参数 | 类型 | 说明 |
|------|------|------|
| `max_concurrent` | int | 最大并发 Embedding 请求数(`embedding.max_concurrent`,默认:`10`) |
-| `provider` | str | `"volcengine"`、`"openai"`、`"vikingdb"` 或 `"jina"` |
+| `provider` | str | `"volcengine"`、`"openai"`、`"vikingdb"`、`"jina"`、`"voyage"`、`"minimax"` 或 `"gemini"` |
| `api_key` | str | API Key |
| `model` | str | 模型名称 |
| `dimension` | int | 向量维度 |
@@ -144,6 +144,7 @@ OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支
- `jina`: Jina AI Embedding API
- `voyage`: Voyage AI Embedding API
- `minimax`: MiniMax Embedding API
+- `gemini`: Google Gemini Embedding API(仅文本;需安装 `google-genai>=1.0.0`)
**minimax provider 配置示例:**
@@ -219,6 +220,51 @@ OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支
获取 API Key: https://jina.ai
+**gemini provider 配置示例:**
+
+> **注意:** 需安装 `pip install "google-genai>=1.0.0"`。异步批量嵌入:`pip install "openviking[gemini-async]"`。
+
+```json
+{
+ "embedding": {
+ "dense": {
+ "provider": "gemini",
+ "api_key": "your-google-api-key",
+ "model": "gemini-embedding-2-preview",
+ "dimension": 3072
+ }
+ }
+}
+```
+
+可用 Gemini 嵌入模型:
+- `gemini-embedding-2-preview`: 8192 token 输入限制, 1–3072 输出维度 (MRL)
+- `gemini-embedding-001`: 2048 token 输入限制, 1–3072 输出维度 (MRL)
+- `text-embedding-004`: 2048 token 输入限制, 768 输出维度(固定)
+
+推荐维度: `768`、`1536` 或 `3072`(默认: `3072`)。
+
+获取 API Key: https://aistudio.google.com/apikey
+
+**非对称检索**(索引和查询使用不同的 task type):
+
+```json
+{
+ "embedding": {
+ "dense": {
+ "provider": "gemini",
+ "api_key": "your-google-api-key",
+ "model": "gemini-embedding-2-preview",
+ "dimension": 3072,
+ "query_param": "RETRIEVAL_QUERY",
+ "document_param": "RETRIEVAL_DOCUMENT"
+ }
+ }
+}
+```
+
+支持的 task type: `RETRIEVAL_QUERY`、`RETRIEVAL_DOCUMENT`、`SEMANTIC_SIMILARITY`、`CLASSIFICATION`、`CLUSTERING`、`CODE_RETRIEVAL_QUERY`、`QUESTION_ANSWERING`、`FACT_VERIFICATION`。
+
#### Sparse Embedding
> **注意:** 火山引擎的 Sparse embedding 从 `doubao-embedding-vision-250615` 模型版本起支持。