From 5904a2b75a550ebd1635b2039e8d97833f1be5eb Mon Sep 17 00:00:00 2001 From: akhil-vamshi-konam Date: Sat, 21 Mar 2026 11:30:51 +0530 Subject: [PATCH] chore: opensearch embedding model dimension configurability --- .../govern/aws-opensearch-embedding.md | 6 +- .../govern/environment-variables.md | 77 ++++++++++--------- docs/self-hosting/govern/plane-ai.md | 48 +++++++++--- 3 files changed, 83 insertions(+), 48 deletions(-) diff --git a/docs/self-hosting/govern/aws-opensearch-embedding.md b/docs/self-hosting/govern/aws-opensearch-embedding.md index e8dcfec..5219843 100644 --- a/docs/self-hosting/govern/aws-opensearch-embedding.md +++ b/docs/self-hosting/govern/aws-opensearch-embedding.md @@ -224,10 +224,12 @@ POST /_plugins/_ml/models//_predict ## Configure Plane -Add the deployed model ID to `/opt/plane/plane.env`: +Add the deployed model ID and configuration to `/opt/plane/plane.env`: ```bash -EMBEDDING_MODEL_ID= +OPENSEARCH_ML_MODEL_ID= +EMBEDDING_MODEL=cohere/embed-v4.0 +OPENSEARCH_EMBEDDING_DIMENSION=1536 ``` Restart Plane and complete the remaining steps in [Enable Plane AI](/self-hosting/govern/plane-ai#configure-an-embedding-model). diff --git a/docs/self-hosting/govern/environment-variables.md b/docs/self-hosting/govern/environment-variables.md index ed943b0..5fd32f3 100644 --- a/docs/self-hosting/govern/environment-variables.md +++ b/docs/self-hosting/govern/environment-variables.md @@ -227,14 +227,15 @@ Use these when routing requests through self-hosted gateways, proxies, or compat These settings are required for semantic search and Plane AI Chat. Configure one of the following options. -| Variable | Description | Required | -| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | -| **EMBEDDING_MODEL_ID** | ID of an existing embedding model deployed in OpenSearch (works with both self-hosted and AWS OpenSearch) | Conditional | -| **EMBEDDING_MODEL** | Embedding model to automatically deploy (e.g., `cohere/embed-v4.0`, `openai/text-embedding-3-small`, `bedrock/amazon.titan-embed-text-v1`). Self-hosted OpenSearch only. | Conditional | -| **COHERE_API_KEY** | API key for Cohere embedding models | Conditional | -| **BR_AWS_ACCESS_KEY_ID** | AWS access key ID for Bedrock Titan embedding | Conditional | -| **BR_AWS_SECRET_ACCESS_KEY** | AWS secret access key for Bedrock Titan embedding | Conditional | -| **BR_AWS_REGION** | AWS region for Bedrock Titan embedding | Conditional | +| Variable | Description | Required | +| ---------------------------------- | ---------------------------------------------------------------------------------------- | ----------- | +| **OPENSEARCH_ML_MODEL_ID** | ID of an existing embedding model deployed in OpenSearch. | Conditional | +| **EMBEDDING_MODEL** | Model used for generating embeddings and query construction (e.g., `cohere/embed-v4.0`). | Required | +| **OPENSEARCH_EMBEDDING_DIMENSION** | The dimension of the embedding model (e.g., `1536`). | Required | +| **COHERE_API_KEY** | API key for Cohere embedding models | Conditional | +| **BR_AWS_ACCESS_KEY_ID** | AWS access key ID for Bedrock Titan embedding | Conditional | +| **BR_AWS_SECRET_ACCESS_KEY** | AWS secret access key for Bedrock Titan embedding | Conditional | +| **BR_AWS_REGION** | AWS region for Bedrock Titan embedding | Conditional | For setup instructions, supported models, and IAM permissions, see [Enable Plane AI](/self-hosting/govern/plane-ai). @@ -292,35 +293,37 @@ For setup instructions, supported models, and IAM permissions, see [Enable Plane ### Plane Intelligence (PI) settings -| Variable | Description | Default Value | -| --------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------- | -| **OPENAI_API_KEY** | API key for OpenAI services used by Plane Intelligence. | | -| **OPENAI_BASE_URL** | Custom base URL for OpenAI-compatible API endpoints. | | -| **CLAUDE_API_KEY** | API key for Anthropic Claude services used by Plane Intelligence. | | -| **CLAUDE_BASE_URL** | Custom base URL for Claude API endpoints. | | -| **GROQ_API_KEY** | API key for Groq services used by Plane Intelligence. | | -| **GROQ_BASE_URL** | Custom base URL for Groq API endpoints. | | -| **COHERE_API_KEY** | API key for Cohere services used by Plane Intelligence. | | -| **COHERE_BASE_URL** | Custom base URL for Cohere API endpoints. | | -| **CUSTOM_LLM_ENABLED** | Enable a custom OpenAI-compatible LLM provider. Set to `true` to enable. | false | -| **CUSTOM_LLM_MODEL_KEY** | Model key identifier for the custom LLM. | gpt-oss-120b | -| **CUSTOM_LLM_BASE_URL** | Base URL for the custom LLM API endpoint. | | -| **CUSTOM_LLM_API_KEY** | API key for the custom LLM provider. | | -| **CUSTOM_LLM_NAME** | Display name for the custom LLM in the Plane UI. | GPT-OSS-120B | -| **CUSTOM_LLM_DESCRIPTION** | Description of the custom LLM shown in the Plane UI. | A self-hosted OpenAI-compatible model | -| **CUSTOM_LLM_MAX_TOKENS** | Maximum token limit for the custom LLM. | 128000 | -| **EMBEDDING_MODEL** | Model used for generating text embeddings for search features. | | -| **BR_AWS_ACCESS_KEY_ID** | AWS access key for Amazon Bedrock integration. | | -| **BR_AWS_SECRET_ACCESS_KEY** | AWS secret key for Amazon Bedrock integration. | | -| **BR_AWS_SESSION_TOKEN** | AWS session token for Amazon Bedrock integration (for temporary credentials). | | -| **FASTAPI_APP_WORKERS** | Number of FastAPI workers for the PI service. | 1 | -| **PLANE_OAUTH_STATE_EXPIRY_SECONDS** | Expiry time (in seconds) for PI OAuth state tokens. | 82800 | -| **CELERY_VECTOR_SYNC_ENABLED** | Enable periodic vector synchronization for AI-powered search. | 0 | -| **CELERY_VECTOR_SYNC_INTERVAL** | Interval (in seconds) for vector synchronization. | 3 | -| **CELERY_WORKSPACE_PLAN_SYNC_ENABLED** | Enable periodic workspace plan synchronization. | 0 | -| **CELERY_WORKSPACE_PLAN_SYNC_INTERVAL** | Interval (in seconds) for workspace plan synchronization. | 86400 | -| **CELERY_DOCS_SYNC_ENABLED** | Enable periodic documents synchronization for AI indexing. | 0 | -| **CELERY_DOCS_SYNC_INTERVAL** | Interval (in seconds) for documents synchronization. | 86400 | +| Variable | Description | Default Value | +| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | +| **OPENAI_API_KEY** | API key for OpenAI services used by Plane Intelligence. | | +| **OPENAI_BASE_URL** | Custom base URL for OpenAI-compatible API endpoints. | | +| **CLAUDE_API_KEY** | API key for Anthropic Claude services used by Plane Intelligence. | | +| **CLAUDE_BASE_URL** | Custom base URL for Claude API endpoints. | | +| **GROQ_API_KEY** | API key for Groq services used by Plane Intelligence. | | +| **GROQ_BASE_URL** | Custom base URL for Groq API endpoints. | | +| **COHERE_API_KEY** | API key for Cohere services used by Plane Intelligence. | | +| **COHERE_BASE_URL** | Custom base URL for Cohere API endpoints. | | +| **CUSTOM_LLM_ENABLED** | Enable a custom OpenAI-compatible LLM provider. Set to `true` to enable. | false | +| **CUSTOM_LLM_MODEL_KEY** | Model key identifier for the custom LLM. | gpt-oss-120b | +| **CUSTOM_LLM_BASE_URL** | Base URL for the custom LLM API endpoint. | | +| **CUSTOM_LLM_API_KEY** | API key for the custom LLM provider. | | +| **CUSTOM_LLM_NAME** | Display name for the custom LLM in the Plane UI. | GPT-OSS-120B | +| **CUSTOM_LLM_DESCRIPTION** | Description of the custom LLM shown in the Plane UI. | A self-hosted OpenAI-compatible model | +| **CUSTOM_LLM_MAX_TOKENS** | Maximum token limit for the custom LLM. | 128000 | +| **EMBEDDING_MODEL** | Model key for generating embeddings (e.g. `cohere/embed-v4.0`). Required for PI API startup when Plane AI is enabled. | | +| **OPENSEARCH_ML_MODEL_ID** | OpenSearch ML model ID for the deployed embedding model. | | +| **OPENSEARCH_EMBEDDING_DIMENSION** | Vector dimension for `knn_vector` fields; must match the embedding model and stay aligned with the API service. See [Plane AI](/self-hosting/govern/plane-ai). | 1536 | +| **BR_AWS_ACCESS_KEY_ID** | AWS access key for Amazon Bedrock integration. | | +| **BR_AWS_SECRET_ACCESS_KEY** | AWS secret key for Amazon Bedrock integration. | | +| **BR_AWS_SESSION_TOKEN** | AWS session token for Amazon Bedrock integration (for temporary credentials). | | +| **FASTAPI_APP_WORKERS** | Number of FastAPI workers for the PI service. | 1 | +| **PLANE_OAUTH_STATE_EXPIRY_SECONDS** | Expiry time (in seconds) for PI OAuth state tokens. | 82800 | +| **CELERY_VECTOR_SYNC_ENABLED** | Enable periodic vector synchronization for AI-powered search. | 0 | +| **CELERY_VECTOR_SYNC_INTERVAL** | Interval (in seconds) for vector synchronization. | 3 | +| **CELERY_WORKSPACE_PLAN_SYNC_ENABLED** | Enable periodic workspace plan synchronization. | 0 | +| **CELERY_WORKSPACE_PLAN_SYNC_INTERVAL** | Interval (in seconds) for workspace plan synchronization. | 86400 | +| **CELERY_DOCS_SYNC_ENABLED** | Enable periodic documents synchronization for AI indexing. | 0 | +| **CELERY_DOCS_SYNC_INTERVAL** | Interval (in seconds) for documents synchronization. | 86400 | ::: details Community Edition diff --git a/docs/self-hosting/govern/plane-ai.md b/docs/self-hosting/govern/plane-ai.md index 97c2395..4d87d95 100644 --- a/docs/self-hosting/govern/plane-ai.md +++ b/docs/self-hosting/govern/plane-ai.md @@ -58,11 +58,18 @@ The custom model should have at least 100 billion parameters for all Plane AI fe Embedding models power semantic search. Plane AI supports: -| Provider | Supported models | -| ----------------------- | ---------------------------------------------------------------- | -| **Cohere** | `cohere/embed-v4.0` | -| **OpenAI** | `openai/text-embedding-ada-002`, `openai/text-embedding-3-small` | -| **AWS Bedrock (Titan)** | `bedrock/amazon.titan-embed-text-v1` | +| Provider | Supported models | Dimension | +| --------------- | -------------------------------------- | --------- | +| **Cohere** | `cohere/embed-v4.0` | 1536 | +| | `cohere/embed-english-v3.0` | 1024 | +| | `cohere/embed-english-v2.0` | 4096 | +| **OpenAI** | `openai/text-embedding-ada-002` | 1536 | +| | `openai/text-embedding-3-small` | 1536 | +| | `openai/text-embedding-3-large` | 3072 | +| **AWS Bedrock** | `bedrock/amazon.titan-embed-text-v1` | 1536 | +| | `bedrock/amazon.titan-embed-text-v2` | 1024 | +| | `bedrock/cohere.embed-english-v3` | 1024 | +| | `bedrock/cohere.embed-multilingual-v3` | 1024 | ## Enable Plane AI services @@ -101,6 +108,10 @@ This activates the Plane AI API, worker, beat-worker, and migrator workloads. Re ::: +:::tip Plane AI API startup checks +On start, the Plane AI container runs an embedding-dimension check against OpenSearch. **OpenSearch must be reachable** at `OPENSEARCH_URL`, and **`EMBEDDING_MODEL` must be set** in your environment or the service will not start. If existing index mappings or the deployed ML model disagree with **`OPENSEARCH_EMBEDDING_DIMENSION`**, startup fails until you align the configuration or rebuild indices (see [Changing the embedding dimension](#changing-the-embedding-dimension) below). +::: + ## Configure an LLM provider Configure at least one LLM provider. Add the relevant variables to `/opt/plane/plane.env`. @@ -160,14 +171,16 @@ OPENSEARCH_INDEX_PREFIX=plane ### Configure an embedding model -Configure exactly one embedding model using one of these options. +You must configure the `EMBEDDING_MODEL` so Plane AI knows which embedding model to construct queries for. Then configure exactly one embedding model deployment using one of these options. #### Option A: Use an existing OpenSearch model ID -If you've already deployed an embedding model in OpenSearch, provide its model ID. This works with both self-hosted and AWS OpenSearch. +If you've already deployed an embedding model in OpenSearch, provide its model ID along with your chosen embedding model and dimension. This works with both self-hosted and AWS OpenSearch. ```bash -EMBEDDING_MODEL_ID=your-model-id +OPENSEARCH_ML_MODEL_ID=your-model-id +EMBEDDING_MODEL=openai/text-embedding-3-small +OPENSEARCH_EMBEDDING_DIMENSION=1536 ``` For AWS OpenSearch, you must deploy the embedding model manually before setting this variable. See [Deploy an embedding model on AWS OpenSearch](/self-hosting/govern/aws-opensearch-embedding). @@ -181,6 +194,7 @@ For self-hosted OpenSearch, Plane can automatically create and deploy the embedd ```bash EMBEDDING_MODEL=cohere/embed-v4.0 COHERE_API_KEY=your-cohere-api-key +OPENSEARCH_EMBEDDING_DIMENSION=1536 ``` **OpenAI:** @@ -188,6 +202,7 @@ COHERE_API_KEY=your-cohere-api-key ```bash EMBEDDING_MODEL=openai/text-embedding-3-small OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx +OPENSEARCH_EMBEDDING_DIMENSION=1536 ``` **AWS Bedrock (Titan):** @@ -197,6 +212,7 @@ EMBEDDING_MODEL=bedrock/amazon.titan-embed-text-v1 BR_AWS_ACCESS_KEY_ID=your-access-key BR_AWS_SECRET_ACCESS_KEY=your-secret-key BR_AWS_REGION=your-region +OPENSEARCH_EMBEDDING_DIMENSION=1536 ``` :::warning Required IAM permission for Bedrock Titan @@ -221,7 +237,7 @@ Replace `` with your `BR_AWS_REGION` value. ::: :::info -Automatic embedding model deployment only works with self-hosted OpenSearch. For AWS OpenSearch, deploy the model manually and use `EMBEDDING_MODEL_ID`. +Automatic embedding model deployment only works with self-hosted OpenSearch. For AWS OpenSearch, deploy the model manually and set `OPENSEARCH_ML_MODEL_ID` to that model’s ID. ::: ## Restart Plane @@ -270,6 +286,20 @@ kubectl exec -n plane $API_POD -- python manage.py manage_search_index --backgro The `--background` flag processes vectorization through Celery workers. This is recommended for instances with large amounts of existing content. +### Changing the embedding dimension + +If you update the model or manually override the dimension size by setting `OPENSEARCH_EMBEDDING_DIMENSION`, you must recreate your search indices so they adopt the new dimension size, then reindex and revectorize your workspace. Ensure that the model associated with your `OPENSEARCH_ML_MODEL_ID` and your `EMBEDDING_MODEL` configuration share this same dimension size. + +Run these commands inside your API container or pod after updating the environment variables and restarting the Plane services: + +```bash +# 1. Rebuild all search indices to apply the new dimension size +python manage.py manage_search_index index rebuild --force + +# 2. Reindex and revectorize all existing documents +python manage.py manage_search_index --background --vectorize document index --force +``` + ## After setup Once configured: