本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 OpenSearch Service 中建立 ML 連接器
Amazon OpenSearch Service 流程架構範本可讓您使用 ml-commons 中提供的建立連接器 API 來設定和安裝 ML 連接器。您可以使用 ML 連接器將 OpenSearch Service 連接到 AWS 其他服務或第三方平台。如需詳細資訊，請參閱[建立第三方 ML 平台的連接器](https://opensearch.org/docs/2.13/ml-commons-plugin/remote-models/connectors/)。Amazon OpenSearch Service 流程架構 API 可讓您自動化 OpenSearch Service 設定和預先處理任務，並可用於建立 ML 連接器。
您必須先執行下列動作，才能在 OpenSearch Service 中建立連接器：
+ 建立一個 Amazon SageMaker AI 網域。
+ 建立 IAM 角色。
+ 設定傳遞角色許可。
+ 在 OpenSearch Dashboards 中映射流程架構和 ml-commons 角色。
如需如何設定 AWS 服務的 ML 連接器的詳細資訊，請參閱 [AWS 服務的 Amazon OpenSearch Service ML 連接器](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ml-amazon-connector.html#connector-sagemaker-prereq)。若要進一步了解如何將 OpenSearch Service ML 連接器與第三方平台搭配使用，請參閱[適用於第三方平台的 Amazon OpenSearch Service ML 連接器](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ml-amazon-connector.html#connector-sagemaker-prereq)。
## 透過流程架構服務建立連接器
若要使用連接器建立流程架構範本，您需要將`POST`請求傳送至 OpenSearch Service 網域端點。您可以使用 cURL、範例 Python 用戶端、Postman 或其他方法來傳送已簽署的請求。`POST` 請求採用下列格式：
```
POST /_plugins/_flow_framework/workflow
{
"name": "Deploy Claude Model",
"description": "Deploy a model using a connector to Claude",
"use_case": "PROVISION",
"version": {
"template": "1.0.0",
"compatibility": [
"2.12.0",
"3.0.0"
]
},
"workflows": {
"provision": {
"nodes": [
{
"id": "create_claude_connector",
"type": "create_connector",
"user_inputs": {
"name": "Claude Instant Runtime Connector",
"version": "1",
"protocol": "aws_sigv4",
"description": "The connector to Bedrock service for Claude model",
"actions": [
{
"headers": {
"x-amz-content-sha256": "required",
"content-type": "application/json"
},
"method": "POST",
"request_body": "{ \"prompt\":\"${parameters.prompt}\", \"max_tokens_to_sample\":${parameters.max_tokens_to_sample}, \"temperature\":${parameters.temperature}, \"anthropic_version\":\"${parameters.anthropic_version}\" }",
"action_type": "predict",
"url": "https://bedrock-runtime.us-west-2.amazonaws.com/model/anthropic.claude-instant-v1/invoke"
}
],
"credential": {
"roleArn": "arn:aws:iam::account-id:role/opensearch-secretmanager-role"
},
"parameters": {
"endpoint": "bedrock-runtime.us-west-2.amazonaws.com",
"content_type": "application/json",
"auth": "Sig_V4",
"max_tokens_to_sample": "8000",
"service_name": "bedrock",
"temperature": "0.0001",
"response_filter": "$.completion",
"region": "us-west-2",
"anthropic_version": "bedrock-2023-05-31"
}
}
}
]
}
}
}
```
如果您的網域位於虛擬私有雲端 (Amazon VPC) 中，您必須連線到 Amazon VPC，請求才能成功建立 AI 連接器。存取 Amazon VPC 因網路組態而異，但通常涉及連線到 VPN 或公司網路。若要檢查您是否可以連線到 OpenSearch Service 網域，請在 Web 瀏覽器`https://{{your-vpc-domain}}.{{region}}.es.amazonaws.com`中導覽至 ，並確認您收到預設的 JSON 回應。（將{{預留位置文字}}取代為您自己的值。
### Python 用戶端範例
Python 用戶端比`HTTP`請求更易於自動化，且具有更好的可重複使用性。若要使用 Python 用戶端建立 AI 連接器，請將下列範例程式碼儲存至 Python 檔案。用戶端需要[AWS 適用於 Python 的 SDK (Boto3)](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ml-amazon-connector.html#connector-sagemaker-prereq)、[Requests：HTTP for Humans](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/ml-amazon-connector.html#connector-sagemaker-prereq) 和 [requests-aws4auth 1.2.3 ](https://pypi.org/project/requests-aws4auth/)套件。
```
import boto3
import requests
from requests_aws4auth import AWS4Auth
host = 'domain-endpoint/'
region = 'region'
service = 'es'
credentials = boto3.Session().get_credentials()
awsauth = AWS4Auth(credentials.access_key, credentials.secret_key, region, service, session_token=credentials.token)
path = '_plugins/_flow_framework/workflow'
url = host + path
payload = {
"name": "Deploy Claude Model",
"description": "Deploy a model using a connector to Claude",
"use_case": "PROVISION",
"version": {
"template": "1.0.0",
"compatibility": [
"2.12.0",
"3.0.0"
]
},
"workflows": {
"provision": {
"nodes": [
{
"id": "create_claude_connector",
"type": "create_connector",
"user_inputs": {
"name": "Claude Instant Runtime Connector",
"version": "1",
"protocol": "aws_sigv4",
"description": "The connector to Bedrock service for Claude model",
"actions": [
{
"headers": {
"x-amz-content-sha256": "required",
"content-type": "application/json"
},
"method": "POST",
"request_body": "{ \"prompt\":\"${parameters.prompt}\", \"max_tokens_to_sample\":${parameters.max_tokens_to_sample}, \"temperature\":${parameters.temperature}, \"anthropic_version\":\"${parameters.anthropic_version}\" }",
"action_type": "predict",
"url": "https://bedrock-runtime.us-west-2.amazonaws.com/model/anthropic.claude-instant-v1/invoke"
}
],
"credential": {
"roleArn": "arn:aws:iam::account-id:role/opensearch-secretmanager-role"
},
"parameters": {
"endpoint": "bedrock-runtime.us-west-2.amazonaws.com",
"content_type": "application/json",
"auth": "Sig_V4",
"max_tokens_to_sample": "8000",
"service_name": "bedrock",
"temperature": "0.0001",
"response_filter": "$.completion",
"region": "us-west-2",
"anthropic_version": "bedrock-2023-05-31"
}
}
}
]
}
}
}
headers = {"Content-Type": "application/json"}
r = requests.post(url, auth=awsauth, json=payload, headers=headers)
print(r.status_code)
print(r.text)
```
#### 預先定義的工作流程範本
Amazon OpenSearch Service 為一些常見的機器學習 (ML) 使用案例提供多個工作流程範本。使用範本可簡化複雜的設定，並為語意或對話搜尋等使用案例提供許多預設值。您可以在呼叫建立工作流程 API 時指定工作流程範本。
+ 若要使用 OpenSearch Service 提供的工作流程範本，請將範本使用案例指定為`use_case`查詢參數。
+ 若要使用自訂工作流程範本，請在請求內文中提供完整範本。如需自訂範本的範例，請參閱範例 JSON 範本或範例 YAML 範本。
#### 範本使用案例
此表格提供不同可用範本的概觀、範本的描述，以及必要參數。
| 範本使用案例 | 說明 | 必要參數 |
| --- | --- | --- |
| `bedrock_titan_embedding_model_deploy` | 建立和部署 Amazon Bedrock 內嵌模型 （預設為 `titan-embed-text-v1` | `create_connector.credential.roleArn` |
| `bedrock_titan_embedding_model_deploy` | 建立和部署 Amazon Bedrock 多模態內嵌模型 （預設為 `titan-embed-text-v1` | `create_connector.credential.roleArn` |
| `cohere_embedding_model_deploy` | 建立和部署 Cohere 內嵌模型 （預設為 embed-english-v3.0)。 | `create_connector.credential.roleArn`, `create_connector.credential.secretArn` |
| `cohere_chat_model_deploy` | 建立和部署 Cohere 聊天模型 （預設為 Cohere Command)。 | `create_connector.credential.roleArn`, `create_connector.credential.secretArn` |
| `open_ai_embedding_model_deploy` | 建立和部署 OpenAI 內嵌模型 （預設為 text-embedding-ada-002)。 | `create_connector.credential.roleArn`, `create_connector.credential.secretArn` |
| `openai_chat_model_deploy` | 建立和部署 OpenAI 聊天模型 （預設為 gpt-3.5-turbo)。 | `create_connector.credential.roleArn`, `create_connector.credential.secretArn` |
| `semantic_search_with_cohere_embedding` | 設定語意搜尋並部署 Cohere 內嵌模型。您必須提供 Cohere 模型的 API 金鑰。 | `create_connector.credential.roleArn`, `create_connector.credential.secretArn` |
| `semantic_search_with_cohere_embedding_query_enricher` | 設定語意搜尋並部署 Cohere 內嵌模型。新增 query\_enricher 搜尋處理器，可設定神經查詢的預設模型 ID。您必須提供 Cohere 模型的 API 金鑰。 | `create_connector.credential.roleArn`, `create_connector.credential.secretArn` |
| `multimodal_search_with_bedrock_titan` | 部署 Amazon Bedrock 多模態模型，並使用 text\_image\_embedding 處理器和用於多模態搜尋的 k-NN 索引來設定擷取管道。您必須提供您的 AWS 登入資料。 | `create_connector.credential.roleArn` |
**注意**
對於需要秘密 ARN 的所有範本，預設值是將金鑰名稱為 "key" 的秘密存放在 AWS Secrets Manager 中。
## 具有預先訓練模型的預設範本
Amazon OpenSearch Service 提供開放原始碼 OpenSearch Service 中未提供的兩個額外預設工作流程範本。
| 範本使用案例 | 說明 |
| --- | --- |
| `semantic_search_with_local_model` | 設定[語意搜尋](https://opensearch.org/docs/2.14/search-plugins/semantic-search/)並部署預先訓練的模型 (`msmarco-distilbert-base-tas-b`)。新增[https://opensearch.org/docs/2.14/search-plugins/search-pipelines/neural-query-enricher/](https://opensearch.org/docs/2.14/search-plugins/search-pipelines/neural-query-enricher/)搜尋處理器，設定神經查詢的預設模型 ID，並建立稱為「my-nlp-index」的連結 k-NN 索引。 |
| `hybrid_search_with_local_model` | 設定[混合式搜尋](https://opensearch.org/docs/2.14/search-plugins/hybrid-search/)並部署預先訓練的模型 (`msmarco-distilbert-base-tas-b`)。新增[https://opensearch.org/docs/2.14/search-plugins/search-pipelines/neural-query-enricher/](https://opensearch.org/docs/2.14/search-plugins/search-pipelines/neural-query-enricher/)搜尋處理器，設定神經查詢的預設模型 ID，並建立稱為「my-nlp-index」的連結 k-NN 索引。 |