Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: add Gemini embedding provider usage and installation guide (#830)
chethanuk5633394583e0
diff --git a/README.md b/README.mdindex 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 VariableAfter 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.mdindex 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.mdindex 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` 模型版本起支持。