Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Konektor Amazon OpenSearch Service MS untuk platform pihak ketiga
Dalam tutorial ini, kita membahas cara membuat konektor dari OpenSearch Service to Cohere. Untuk informasi selengkapnya tentang konektor, lihat [Konektor yang didukung](https://opensearch.org/docs/latest/ml-commons-plugin/remote-models/connectors/#supported-connectors).
Saat Anda menggunakan konektor pembelajaran mesin Amazon OpenSearch Service (ML) dengan model jarak jauh eksternal, Anda harus menyimpan kredenal otorisasi spesifik Anda. AWS Secrets Manager Ini bisa berupa kunci API, atau kombinasi nama pengguna dan kata sandi. Ini berarti Anda juga perlu membuat peran IAM yang memungkinkan akses OpenSearch Layanan untuk membaca dari Secrets Manager.
**Topics**
+ [Prasyarat](#connector-external-prereq)
+ [Buat konektor OpenSearch Service](#connector-external-create)
## Prasyarat
Untuk membuat konektor untuk Cohere atau penyedia eksternal apa pun dengan OpenSearch Layanan, Anda harus memiliki peran IAM yang memberikan akses OpenSearch Layanan AWS Secrets Manager, tempat Anda menyimpan kredensil Anda. Anda juga harus menyimpan kredensialnya di Secrets Manager.
### Membuat peran IAM
Siapkan peran IAM untuk mendelegasikan izin Secrets Manager ke Layanan. OpenSearch Anda juga dapat menggunakan `SecretManagerReadWrite` peran yang ada. Untuk membuat peran baru, lihat [Membuat peran IAM (konsol)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html#roles-creatingrole-user-console) di *Panduan Pengguna IAM*. Jika Anda membuat peran baru alih-alih menggunakan peran AWS terkelola, ganti `opensearch-secretmanager-role` dalam tutorial ini dengan nama peran Anda sendiri.
1. Lampirkan kebijakan IAM terkelola berikut ke peran baru Anda untuk memungkinkan OpenSearch Layanan mengakses nilai Secrets Manager Anda. Untuk melampirkan kebijakan ke peran, lihat [Menambahkan Izin Identitas IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policies-console).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"secretsmanager:GetSecretValue"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
1. Ikuti instruksi dalam [Memodifikasi kebijakan kepercayaan peran](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-managingrole_edit-trust-policy) untuk mengedit hubungan kepercayaan peran. Dalam kebijakan berikut, ganti *service-principal* dengan salah satu prinsip layanan berikut untuk OpenSearch Layanan atau Tanpa Server: OpenSearch
**Untuk OpenSearch Layanan**
`opensearchservice.amazonaws.com`
**Untuk Tanpa OpenSearch Server**
`ml.opensearchservice.amazonaws.com`
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"sts:AssumeRole"
],
"Effect": "Allow",
"Principal": {
"Service": [
"service-principle"
]
}
}
]
}
```
------
Kami menyarankan Anda menggunakan tombol `aws:SourceAccount` dan `aws:SourceArn` kondisi untuk membatasi akses ke domain tertentu. Itu `SourceAccount` adalah Akun AWS ID milik pemilik domain, dan `SourceArn` adalah ARN dari domain. Misalnya, Anda dapat menambahkan blok kondisi berikut ke kebijakan kepercayaan:
```
"Condition": {
"StringEquals": {
"aws:SourceAccount": "account-id"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:es:region:account-id:domain/domain-name"
}
}
```
### Mengatur Konfigurasi Izin
Untuk membuat konektor, Anda memerlukan izin untuk meneruskan peran IAM ke OpenSearch Layanan. Anda juga memerlukan akses ke tindakan `es:ESHttpPost`. Untuk memberikan kedua izin ini, lampirkan kebijakan berikut ke peran IAM yang kredensialnya digunakan untuk menandatangani permintaan:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::111122223333:role/opensearch-secretmanager-role"
},
{
"Effect": "Allow",
"Action": "es:ESHttpPost",
"Resource": "arn:aws:es:us-east-1:111122223333:domain/domain-name/*"
}
]
}
```
------
Jika pengguna atau peran Anda tidak memiliki `iam:PassRole` izin untuk meneruskan peran Anda, Anda mungkin mengalami kesalahan otorisasi saat mencoba mendaftarkan repositori di langkah berikutnya.
### Mengatur AWS Secrets Manager
*Untuk menyimpan kredensyal otorisasi Anda di Secrets Manager, lihat [Membuat AWS Secrets Manager rahasia di Panduan](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) Pengguna.AWS Secrets Manager *
Setelah Secrets Manager menerima pasangan nilai kunci Anda sebagai rahasia, Anda menerima ARN dengan format:. `arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret-a1b2c3` Simpan catatan ARN ini, saat Anda menggunakannya dan kunci Anda saat membuat konektor di langkah berikutnya.
### Petakan peran ML di OpenSearch Dasbor (jika menggunakan kontrol akses berbutir halus)
Kontrol akses berbutir halus memperkenalkan langkah tambahan saat menyiapkan konektor. Bahkan jika Anda menggunakan autentikasi basic HTTP untuk semua tujuan lain, Anda perlu memetakan peran `ml_full_access` ke IAM role Anda yang memiliki izin `iam:PassRole` untuk meneruskan `opensearch-sagemaker-role`.
1. Arahkan ke plugin OpenSearch Dasbor untuk domain OpenSearch Layanan Anda. Anda dapat menemukan titik akhir Dasbor di dasbor domain Anda di konsol OpenSearch Layanan.
1. Dari menu utama pilih **Keamanan**, **Peran, dan pilih peran** **ml\$1full\$1access**.
1. Pilih **Pengguna yang Dipetakan**, **Kelola pemetaan**.
1. Di bawah **peran Backend**, tambahkan ARN dari peran yang memiliki izin untuk diteruskan. `opensearch-sagemaker-role`
```
arn:aws:iam::account-id:role/role-name
```
1. Pilih **Peta** dan konfirmasikan pengguna atau peran muncul di bawah **Pengguna yang dipetakan**.
## Buat konektor OpenSearch Service
Untuk membuat konektor, kirim `POST` permintaan ke titik akhir domain OpenSearch Layanan. Anda dapat menggunakan curl, contoh klien Python, Postman, atau metode lain untuk mengirim permintaan yang ditandatangani. Perhatikan bahwa Anda tidak dapat menggunakan `POST` permintaan di konsol Kibana. Permintaan mengambil format berikut:
```
POST domain-endpoint/_plugins/_ml/connectors/_create
{
"name": "Cohere Connector: embedding",
"description": "The connector to cohere embedding model",
"version": 1,
"protocol": "http",
"credential": {
"secretArn": "arn:aws:secretsmanager:region:account-id:secret:cohere-key-id",
"roleArn": "arn:aws:iam::account-id:role/opensearch-secretmanager-role"
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"url": "https://api.cohere.ai/v1/embed",
"headers": {
"Authorization": "Bearer ${credential.secretArn.cohere-key-used-in-secrets-manager}"
},
"request_body": "{ \"texts\": ${parameters.texts}, \"truncate\": \"END\" }"
}
]
}
```
Badan permintaan untuk permintaan ini berbeda dari permintaan konektor sumber terbuka dalam dua cara. Di dalam `credential` lapangan, Anda melewati ARN untuk peran IAM yang memungkinkan OpenSearch Layanan membaca dari Secrets Manager, bersama dengan ARN untuk rahasia apa. Di `headers` lapangan, Anda merujuk pada rahasia menggunakan kunci rahasia dan fakta itu berasal dari ARN.
Jika domain Anda berada dalam virtual private cloud (VPC), komputer Anda harus terhubung ke VPC agar permintaan berhasil membuat AI connetor. Mengakses VPC bervariasi menurut konfigurasi jaringan, tetapi biasanya melibatkan koneksi ke VPN atau jaringan perusahaan. Untuk memastikan bahwa Anda dapat mencapai domain OpenSearch Layanan, `https://your-vpc-domain.region.es.amazonaws.com` navigasikan ke browser web dan verifikasi bahwa Anda menerima respons JSON default.
### Contoh klien Python
Klien Python lebih mudah diotomatisasi daripada permintaan HTTP dan memiliki kegunaan ulang yang lebih baik. Untuk membuat konektor AI dengan klien Python, simpan kode contoh berikut ke file Python. Klien membutuhkan [AWS SDK untuk Python (Boto3)](https://aws.amazon.com/sdk-for-python/), [https://requests.readthedocs.io/en/latest/](https://requests.readthedocs.io/en/latest/), dan [https://pypi.org/project/requests-aws4auth/](https://pypi.org/project/requests-aws4auth/)paket.
```
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/_ml/connectors/_create'
url = host + path
payload = {
"name": "Cohere Connector: embedding",
"description": "The connector to cohere embedding model",
"version": 1,
"protocol": "http",
"credential": {
"secretArn": "arn:aws:secretsmanager:region:account-id:secret:cohere-key-id",
"roleArn": "arn:aws:iam::account-id:role/opensearch-secretmanager-role"
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"url": "https://api.cohere.ai/v1/embed",
"headers": {
"Authorization": "Bearer ${credential.secretArn.cohere-key-used-in-secrets-manager}"
},
"request_body": "{ \"texts\": ${parameters.texts}, \"truncate\": \"END\" }"
}
]
}
headers = {"Content-Type": "application/json"}
r = requests.post(url, auth=awsauth, json=payload, headers=headers)
print(r.status_code)
print(r.text)
```