Skip to content

Commit 21d259d

Browse files
danciaclaradanciaclara
committed
Plane AI for Commercial Edition
1 parent 7d399c6 commit 21d259d

4 files changed

Lines changed: 549 additions & 0 deletions

File tree

‎docs/.vitepress/config.mts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -272,6 +272,14 @@ export default withMermaid(
272272
},
273273
{ text: "DNS for Intake Email", link: "/self-hosting/govern/configure-dns-email-service" },
274274
{ text: "OpenSearch for search", link: "/self-hosting/govern/advanced-search" },
275+
{
276+
text: "Plane AI",
277+
link: "/self-hosting/govern/plane-ai",
278+
collapsed: true,
279+
items: [
280+
{ text: "AWS OpenSearch embedding", link: "/self-hosting/govern/aws-opensearch-embedding" },
281+
],
282+
},
275283
{ text: "External secrets", link: "/self-hosting/govern/external-secrets" },
276284
{ text: "External reverse proxy", link: "/self-hosting/govern/reverse-proxy" },
277285
{ text: "Private storage buckets", link: "/self-hosting/govern/private-bucket" },

‎docs/self-hosting/govern/aws-opensearch-embedding.md‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
---
2+
title: AWS OpenSearch embedding
3+
description: Step-by-step guide to deploying a Cohere embedding model on AWS OpenSearch for use with Plane AI semantic search.
4+
keywords: aws opensearch, embedding model, cohere, plane ai, semantic search, ml commons, opensearch connector
5+
---
6+
7+
# Deploy an embedding model on AWS OpenSearch
8+
9+
This guide walks you through deploying a Cohere embedding model on AWS OpenSearch (managed) for Plane AI semantic search.
10+
11+
For other connector blueprints and embedding model configurations, see the [OpenSearch ML Commons remote inference blueprints](https://github.com/opensearch-project/ml-commons/tree/2.x/docs/remote_inference_blueprints).
12+
13+
## Before you begin
14+
15+
Make sure you have:
16+
17+
- An AWS OpenSearch domain with **fine-grained access control** enabled.
18+
- Admin access to OpenSearch Dashboards.
19+
- AWS CLI configured locally.
20+
- An IAM user with permissions to create roles, policies, and access Secrets Manager.
21+
- A Cohere API key.
22+
23+
## Create an IAM policy
24+
25+
1. Go to **IAM → Policies → Create Policy**.
26+
2. Select **JSON** and paste the following:
27+
28+
```json
29+
{
30+
"Version": "2012-10-17",
31+
"Statement": [
32+
{
33+
"Sid": "PassRoleAccess",
34+
"Effect": "Allow",
35+
"Action": "iam:PassRole",
36+
"Resource": "arn:aws:iam::<aws-account-number>:role/plane-opensearch-access-role"
37+
},
38+
{
39+
"Sid": "SecretManagerAccess",
40+
"Effect": "Allow",
41+
"Action": [
42+
"secretsmanager:GetSecretValue",
43+
"secretsmanager:DescribeSecret",
44+
"secretsmanager:ListSecrets"
45+
],
46+
"Resource": "*"
47+
}
48+
]
49+
}
50+
```
51+
52+
3. Click **Next**, name the policy `plane-opensearch-access-policy`, and click **Create Policy**.
53+
54+
## Create an IAM role
55+
56+
Create an IAM role that OpenSearch can assume to access Secrets Manager.
57+
58+
1. Go to **IAM → Roles → Create Role**.
59+
2. Name the role `plane-opensearch-access-role`.
60+
3. Set this **Trust Relationship**:
61+
62+
```json
63+
{
64+
"Version": "2012-10-17",
65+
"Statement": [
66+
{
67+
"Effect": "Allow",
68+
"Principal": {
69+
"Service": "ec2.amazonaws.com"
70+
},
71+
"Action": "sts:AssumeRole"
72+
},
73+
{
74+
"Effect": "Allow",
75+
"Principal": {
76+
"AWS": "arn:aws:iam::<aws-account-number>:user/<opensearch-user>"
77+
},
78+
"Action": "sts:AssumeRole"
79+
}
80+
]
81+
}
82+
```
83+
84+
4. Attach the `plane-opensearch-access-policy` you created in Step 1.
85+
5. Click **Create Role** and note the role ARN.
86+
87+
## Grant ML permissions to the IAM role
88+
89+
1. Open **OpenSearch Dashboards**.
90+
2. Go to **Security → Roles → `ml_full_access`**.
91+
3. Open the **Mapped users** tab and click **Map users**.
92+
4. Under **Backend roles**, add the role ARN:
93+
94+
```
95+
arn:aws:iam::<aws-account-number>:role/plane-opensearch-access-role
96+
```
97+
98+
## Assume the role locally
99+
100+
Run this command to get temporary credentials:
101+
102+
```bash
103+
aws sts assume-role \
104+
--role-arn arn:aws:iam::<aws-account-number>:role/plane-opensearch-access-role \
105+
--role-session-name session
106+
```
107+
108+
Export the credentials from the response:
109+
110+
```bash
111+
export AWS_ACCESS_KEY_ID=<AccessKeyId>
112+
export AWS_SECRET_ACCESS_KEY=<SecretAccessKey>
113+
export AWS_SESSION_TOKEN=<SessionToken>
114+
```
115+
116+
## Store the Cohere API key in Secrets Manager
117+
118+
1. Go to **Secrets Manager → Store a new secret**.
119+
2. Select **Other type of secret**.
120+
3. Set the key to `azure_ai_foundry_key_cohere` and the value to your Cohere API key.
121+
4. Click **Next**, name the secret `plane-ai/cohere`, and click **Store**.
122+
5. Note the **Secret ARN** — you'll need it in the next step.
123+
124+
## Create a Cohere connector in OpenSearch
125+
126+
Using the temporary credentials from Step 4, send a `POST` request to your OpenSearch cluster.
127+
128+
**Endpoint:** `POST https://<opensearch-domain>/_plugins/_ml/connectors/_create`
129+
130+
**Request body:**
131+
132+
```json
133+
{
134+
"name": "Cohere",
135+
"description": "Cohere embedding connector",
136+
"version": "1",
137+
"protocol": "http",
138+
"parameters": {
139+
"endpoint": "https://azureaitrials-resource.services.ai.azure.com/models",
140+
"model": "embed-v-4-0",
141+
"api_version": "2024-05-01-preview",
142+
"input_type": "search_document",
143+
"truncate": "END"
144+
},
145+
"credential": {
146+
"secretArn": "<cohere-secret-arn>",
147+
"roleArn": "arn:aws:iam::<aws-account-number>:role/plane-opensearch-access-role"
148+
},
149+
"actions": [
150+
{
151+
"action_type": "predict",
152+
"method": "POST",
153+
"url": "${parameters.endpoint}/embeddings?api-version=${parameters.api_version}",
154+
"headers": {
155+
"api-key": "${credential.secretArn.azure_ai_foundry_key_cohere}",
156+
"x-ms-model-mesh-model-name": "embed-v-4-0"
157+
},
158+
"request_body": "{ \"texts\": ${parameters.texts}, \"truncate\": \"${parameters.truncate}\", \"model\": \"${parameters.model}\", \"input_type\": \"${parameters.input_type}\" }",
159+
"pre_process_function": "connector.pre_process.cohere.embedding",
160+
"post_process_function": "connector.post_process.cohere.embedding"
161+
}
162+
]
163+
}
164+
```
165+
166+
Save the `connector_id` from the response.
167+
168+
## Configure the OpenSearch cluster
169+
170+
Run these commands in **Dev Tools** in OpenSearch Dashboards.
171+
172+
### Allow the connector's external endpoints
173+
174+
```json
175+
PUT /_cluster/settings
176+
{
177+
"persistent": {
178+
"plugins.ml_commons.trusted_connector_endpoints_regex": [
179+
"^https://api\\.cohere\\.ai(/.*)?$",
180+
"^https://azureaitrials-resource\\.services\\.ai\\.azure\\.com(/.*)?$"
181+
]
182+
}
183+
}
184+
```
185+
186+
### Register the embedding model
187+
188+
```json
189+
POST /_plugins/_ml/models/_register
190+
{
191+
"name": "cohere_4_0_embed",
192+
"function_name": "remote",
193+
"connector_id": "<connector-id>",
194+
"description": "Cohere Embedding Model"
195+
}
196+
```
197+
198+
Save the `model_id` from the response.
199+
200+
### Deploy the model
201+
202+
```
203+
POST /_plugins/_ml/models/<model_id>/_deploy
204+
```
205+
206+
### Verify deployment status
207+
208+
```
209+
GET /_plugins/_ml/models/<model_id>
210+
```
211+
212+
Wait until the response shows:
213+
214+
```json
215+
"model_state": "DEPLOYED"
216+
```
217+
218+
### Test inference (optional)
219+
220+
```json
221+
POST /_plugins/_ml/models/<model_id>/_predict
222+
{
223+
"parameters": {
224+
"inputs": ["hello world"]
225+
}
226+
}
227+
```
228+
229+
## Configure Plane
230+
231+
Add the deployed model ID to `/opt/plane/plane.env`:
232+
233+
```bash
234+
EMBEDDING_MODEL_ID=<model_id>
235+
```
236+
237+
Restart Plane and complete the remaining steps in [Enable Plane AI](/self-hosting/govern/plane-ai#configure-an-embedding-model).

‎docs/self-hosting/govern/environment-variables.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,63 @@ This is where you'll make all configuration changes. Remember to restart the ins
152152
| `OPENSEARCH_PASSWORD` | Authentication password | `your-secure-password` |
153153
| `OPENSEARCH_INDEX_PREFIX` | Prefix for all index names (useful for multi-tenant setups) | (empty) |
154154

155+
156+
### Plane AI
157+
158+
#### Plane AI replicas
159+
160+
To start Plane AI services, set each replica count to `1`:
161+
162+
| Variable | Description | Required |
163+
|----------|-------------|----------|
164+
| `PI_API_REPLICAS` | Plane AI API replica count | Yes |
165+
| `PI_BEAT_REPLICAS` | Plane AI Beat Worker replica count | Yes |
166+
| `PI_WORKER_REPLICAS` | Plane AI Worker replica count | Yes |
167+
| `PI_MIGRATOR_REPLICAS` | Plane AI Migrator replica count | Yes |
168+
169+
#### LLM provider API keys
170+
171+
Plane AI supports multiple LLM providers. Configure one or more by adding their API keys.
172+
173+
| Variable | Description | Required |
174+
|----------|-------------|----------|
175+
| `OPENAI_API_KEY` | API key for OpenAI models | Optional |
176+
| `CLAUDE_API_KEY` | API key for Anthropic models | Optional |
177+
| `GROQ_API_KEY` | API key for speech-to-text features | Optional |
178+
| `CUSTOM_LLM_ENABLED` | Set to `true` to use a custom LLM with an OpenAI-compatible API | Optional |
179+
| `CUSTOM_LLM_MODEL_KEY` | Identifier key for the custom model | Optional |
180+
| `CUSTOM_LLM_BASE_URL` | Base URL of the custom model's OpenAI-compatible endpoint | Optional |
181+
| `CUSTOM_LLM_API_KEY` | API key for the custom endpoint | Optional |
182+
| `CUSTOM_LLM_NAME` | Display name for the custom model | Optional |
183+
| `CUSTOM_LLM_DESCRIPTION` | Description of the custom model | Optional |
184+
| `CUSTOM_LLM_MAX_TOKENS` | Maximum token limit for the custom model | Optional |
185+
186+
#### Provider base URLs
187+
188+
Use these when routing requests through self-hosted gateways, proxies, or compatible third-party endpoints.
189+
190+
| Variable | Description | Default |
191+
|----------|-------------|---------|
192+
| `OPENAI_BASE_URL` | Custom base URL for OpenAI-compatible APIs | OpenAI |
193+
| `CLAUDE_BASE_URL` | Custom base URL for Claude-compatible APIs | Anthropic |
194+
| `COHERE_BASE_URL` | Custom base URL for Cohere APIs | Cohere |
195+
| `GROQ_BASE_URL` | Custom base URL for Groq APIs | Groq |
196+
197+
#### Embedding model configuration
198+
199+
These settings are required for semantic search and Plane AI Chat. Configure one of the following options.
200+
201+
| Variable | Description | Required |
202+
|----------|-------------|----------|
203+
| `EMBEDDING_MODEL_ID` | ID of an existing embedding model deployed in OpenSearch (works with both self-hosted and AWS OpenSearch) | Conditional |
204+
| `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 |
205+
| `COHERE_API_KEY` | API key for Cohere embedding models | Conditional |
206+
| `BR_AWS_ACCESS_KEY_ID` | AWS access key ID for Bedrock Titan embedding | Conditional |
207+
| `BR_AWS_SECRET_ACCESS_KEY` | AWS secret access key for Bedrock Titan embedding | Conditional |
208+
| `BR_AWS_REGION` | AWS region for Bedrock Titan embedding | Conditional |
209+
210+
For setup instructions, supported models, and IAM permissions, see [Enable Plane AI](/self-hosting/govern/plane-ai).
211+
155212
### API settings
156213

157214
| Variable | Description | Default Value |

0 commit comments

Comments
 (0)