Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Panduan integrasi
Seluruh solusi dirancang agar mudah diperluas. Lapisan orkestrasi dari solusi ini dibangun menggunakan. [LangChain](https://www.langchain.com/) Anda dapat menambahkan penyedia model, basis pengetahuan, atau jenis memori percakapan apa pun yang didukung oleh LangChain (atau pihak ketiga yang menyediakan LangChain konektor untuk komponen ini) ke solusi ini.
## Memperluas didukung LLMs
Untuk menambahkan penyedia model lain, seperti penyedia LLM khusus, Anda harus memperbarui tiga komponen solusi berikut:
1. Buat tumpukan `TextUseCase` CDK baru, yang menyebarkan aplikasi obrolan yang dikonfigurasi dengan penyedia LLM kustom Anda:
1. [Kloning [GitHub repositori](https://github.com/aws-solutions/generative-ai-application-builder-on-aws) solusi ini, dan siapkan lingkungan build Anda dengan mengikuti instruksi yang diberikan dalam file README.md.](https://github.com/aws-solutions/generative-ai-application-builder-on-aws/blob/main/README.md)
1. Salin (atau buat baru) `source/infrastructure/lib/bedrock-chat-stack.ts` file, tempel ke direktori yang sama, dan ganti namanya menjadi`custom-chat-stack.ts`.
1. Ganti nama kelas dalam file menjadi yang sesuai, seperti`CustomLLMChat`.
1. Anda dapat memilih untuk menambahkan rahasia Secrets Manager ke tumpukan ini, yang menyimpan kredensi Anda untuk LLM kustom Anda. Anda dapat mengambil kredensi ini selama pemanggilan model di lapisan Lambda obrolan yang dibahas di paragraf berikutnya.
1. Bangun dan lampirkan layer Lambda yang berisi pustaka Python dari penyedia model yang akan ditambahkan. Untuk aplikasi obrolan kasus penggunaan Amazon Bedrock, pustaka `langchain-aws` Python berisi konektor khusus di atas paket untuk terhubung ke penyedia LangChain model AWS (Amazon Bedrock SageMaker dan AI), basis pengetahuan (Amazon Kendra dan Amazon Bedrock Knowledge Bases), dan jenis memori (seperti DynamoDB). Demikian pula, penyedia model lain memiliki konektor sendiri. Lapisan ini membantu Anda melampirkan pustaka Python penyedia model ini sehingga Anda dapat menggunakan konektor ini di lapisan Lambda obrolan, yang memanggil LLM (langkah 3). Dalam solusi ini, bundler aset khusus digunakan untuk membangun lapisan Lambda, yang dilampirkan menggunakan aspek CDK. Untuk membuat layer baru untuk pustaka penyedia model kustom:
1. Arahkan ke `LambdaAspects` kelas dalam `source/infrastructure/lib/utils/lambda-aspects.ts` file.
1. Ikuti petunjuk tentang cara memperluas fungsionalitas kelas aspek Lambda yang disediakan dalam file (seperti menambahkan `getOrCreateLangchainLayer` metode). Untuk menggunakan metode baru ini (misalnya,`getOrCreateCustomLLMLayer`), perbarui juga `LLM_LIBRARY_LAYER_TYPES` enum dalam `source/infrastructure/lib/utils/constants.ts` file.
1. Perluas fungsi `chat` Lambda untuk mengimplementasikan pembangun, klien, dan penangan untuk penyedia baru.
`source/lambda/chat`Berisi LangChain koneksi untuk berbeda LLMs bersama dengan kelas pendukung untuk membangun ini LLMs. Kelas pendukung ini mengikuti pola desain Builder dan Object Oriented untuk membuat LLM.
Setiap handler (misalnya,`bedrock_handler.py`) pertama membuat *klien*, memeriksa lingkungan untuk variabel lingkungan yang diperlukan, dan kemudian memanggil `get_model` metode untuk mendapatkan kelas LangChain LLM. Metode generate kemudian dipanggil untuk memanggil LLM dan mendapatkan responsnya. LangChain saat ini mendukung fungsionalitas streaming untuk Amazon Bedrock, tetapi tidak SageMaker AI. Berdasarkan fungsionalitas streaming atau non-streaming, WebSocket handler yang sesuai (`WebsocketStreamingCallbackHandler`atau`WebsocketHandler`) dipanggil untuk mengirim respons kembali ke WebSocket koneksi menggunakan metode ini`post_to_connection`.
`clients/builder`Folder berisi kelas yang membantu membangun LLM Builder menggunakan pola Builder. Pertama, a `use_case_config` diambil dari toko konfigurasi DynamoDB, yang menyimpan detail tentang jenis basis pengetahuan, memori percakapan, dan model apa yang akan dibangun. Ini juga berisi detail model yang relevan seperti parameter model dan petunjuk. Builder kemudian membantu mengikuti langkah-langkah untuk membuat basis pengetahuan, membuat memori percakapan untuk mempertahankan konteks percakapan untuk LLM, mengatur LangChain panggilan balik yang sesuai untuk kasus streaming dan non-streaming, dan membuat model LLM berdasarkan konfigurasi model yang disediakan. Konfigurasi DynamoDB disimpan pada saat pembuatan kasus penggunaan saat Anda menerapkan kasus penggunaan dari dasbor Deployment (atau saat disediakan oleh pengguna dalam penerapan tumpukan kasus penggunaan mandiri tanpa dasbor Deployment).
`clients/factories`Subfolder membantu mengatur memori percakapan dan kelas basis pengetahuan yang sesuai, berdasarkan konfigurasi LLM. Ini memungkinkan ekstensi mudah ke basis pengetahuan atau jenis memori lain yang Anda ingin implementasi Anda dukung.
`shared`Subfolder berisi implementasi spesifik dari basis pengetahuan dan memori percakapan yang dipakai di dalam pabrik oleh pembangun. Ini juga berisi Amazon Kendra dan Amazon Bedrock Knowledge Base retriever yang dipanggil dalam LangChain untuk mengambil dokumen untuk kasus penggunaan RAG, bersama dengan callback, yang digunakan oleh model LLM. LangChain
LangChain Implementasi menggunakan LangChain Expression Language (LCEL) untuk menyusun rantai percakapan bersama-sama. `RunnableWithMessageHistory`class digunakan untuk memelihara riwayat percakapan dengan rantai LCEL khusus, memungkinkan fungsionalitas seperti mengembalikan dokumen sumber dan menggunakan pertanyaan yang diulang (atau disambiguasi) yang dikirim ke basis pengetahuan untuk juga dikirim ke LLM.
Untuk membuat implementasi sendiri dari penyedia kustom, Anda dapat:
1. Salin `bedrock_handler.py` file dan buat handler kustom Anda (misalnya,`custom_handler.py`), yang membuat klien kustom Anda (misalnya,`CustomProviderClient`) (ditentukan dalam langkah berikut.)
1. `bedrock_client.py`Salin di folder klien. Ubah nama menjadi `custom_provider_client.py` (atau nama penyedia model spesifik Anda, seperti`CustomProvider`). Beri nama kelas di dalamnya dengan tepat, seperti `CustomProviderClient` yang mewarisi`LLMChatClient`.
Anda dapat menggunakan metode yang disediakan oleh `LLMChatClient` atau menulis implementasi Anda sendiri untuk mengganti ini.
`get_model`Metode ini membangun `CustomProviderBuilder` (lihat langkah berikut), dan memanggil `construct_chat_model` metode yang membangun model obrolan menggunakan langkah-langkah pembangun. Metode ini bertindak sebagai *Direktur* dalam pola pembangun.
1. Salin `clients/builders/bedrock_builder.py` dan ganti namanya menjadi `custom_provider_builder.py` dan kelas di dalamnya menjadi `CustomProviderBuilder` yang mewarisi LLMBuilder ()`llm_builder.py`. Anda dapat menggunakan metode yang disediakan oleh LLMBuilder atau menulis implementasi Anda sendiri untuk mengganti ini. Langkah-langkah pembangun dipanggil secara berurutan di dalam `construct_chat_model` metode klien, seperti`set_model_defaults`,`set_knowledge_base`, dan`set_conversation_memory`.
`set_llm_model`Metode ini akan membuat model LLM aktual menggunakan semua nilai yang ditetapkan menggunakan metode yang dipanggil sebelumnya. Secara khusus, Anda dapat membuat LLM RAG (`CustomProviderRetrievalLLM`) atau non-RAG (`CustomProviderLLM`), berdasarkan `rag_enabled variable` yang diambil dari konfigurasi LLM di DynamoDB.
Konfigurasi ini diambil dalam `retrieve_use_case_config` metode di `LLMChatClient` kelas.
1. Terapkan `CustomProviderRetrievalLLM` implementasi `CustomProviderLLM` atau implementasi Anda di `llm_models` subfolder berdasarkan apakah Anda memerlukan kasus penggunaan RAG atau non-RAG. Sebagian besar fungsionalitas untuk mengimplementasikan model ini disediakan di `RetrievalLLM` kelasnya masing-masing, untuk kasus penggunaan non-RAG dan RAG. `BaseLangChainModel`
Anda dapat menyalin `llm_models/bedrock.py` file dan membuat perubahan yang diperlukan untuk memanggil LangChain model yang merujuk ke penyedia khusus Anda. Misalnya, Amazon Bedrock menggunakan `ChatBedrock` kelas untuk membuat model obrolan menggunakan LangChain.
*Metode generate menghasilkan respons LLM menggunakan rantai LangChain LCEL.*
Anda juga dapat menggunakan `get_clean_model_params` metode ini untuk membersihkan parameter model per LangChain atau persyaratan model Anda.
## Memperluas alat Strands yang didukung
Solusi ini memungkinkan Anda untuk membangun dan menyebarkan server MCP, agen AI, dan alur kerja multi-agen. Dalam pengalaman Agen Builder, Anda dapat melampirkan server MCP untuk memberi agen Anda kemampuan tambahan. Selain server MCP, Anda dapat memanfaatkan alat bawaan yang disediakan oleh [Strands](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/) (kerangka kerja dasar yang digunakan oleh solusi).
Di luar kotak, solusinya sudah dikonfigurasi sebelumnya dengan alat Strands berikut:
+ Waktu Saat Ini (diaktifkan secara default)
+ Kalkulator (diaktifkan secara default)
+ Lingkungan
**Pemilihan MCP Server dan Tools di wizard Agent Builder yang menampilkan alat Strands bawaan**
![\[alat untaian bawaan\]](http://docs.aws.amazon.com/id_id/solutions/latest/generative-ai-application-builder-on-aws/images/builtin-strands-tools.png)
Untuk memperluas agen Anda dengan alat Strands tambahan, ikuti proses empat langkah yang diuraikan di bagian ini.
### Langkah 1: Temukan alat Strands
Jelajahi [alat Strands yang tersedia](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/#available-tools) untuk mengidentifikasi alat yang ingin Anda gunakan. Setiap alat memiliki kemampuan dan persyaratan konfigurasi khusus.
[Misalnya, untuk menambahkan kemampuan pengambilan Amazon Bedrock Knowledge Base, Anda akan menggunakan alat pengambilan.](https://github.com/strands-agents/tools/blob/main/src/strands_tools/retrieve.py)
### Langkah 2: Perbarui parameter SSM
Agar alat tersedia di UI penerapan Agent Builder, perbarui parameter AWS Systems Manager Parameter Store yang menentukan alat Strands mana yang didukung.
1. Arahkan ke AWS Systems Manager Parameter Store di akun AWS Anda.
1. Temukan parameternya: `/gaab//strands-tools`
1. Tambahkan konfigurasi alat Anda ke akhir daftar yang ada menggunakan struktur JSON berikut:
```
{
"name": "Bedrock KB Retrieve",
"description": "Retrieve information from Bedrock Knowledge Base",
"value": "retrieve",
"category": "AI",
"isDefault": false
}
```
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/solutions/latest/generative-ai-application-builder-on-aws/integration-guide.html)
### Langkah 3: Konfigurasikan variabel lingkungan
Banyak alat Strands memerlukan variabel lingkungan untuk konfigurasi. Anda dapat mengatur variabel-variabel ini dengan dua cara:
**Opsi 1: Konfigurasi langsung pada AgentCore Runtime**
Perbarui agen yang diterapkan secara langsung di Amazon Bedrock AgentCore Runtime dengan variabel lingkungan yang diperlukan.
**Opsi 2: Parameter Model di wizard penerapan**
Tambahkan variabel lingkungan selama langkah pemilihan Model di wizard Agent Builder menggunakan bagian Parameter Model. Variabel lingkungan yang mengikuti konvensi penamaan `ENV__` akan secara otomatis dimuat saat runtime ke lingkungan eksekusi agen sebagai``.
Contoh:
+ `ENV_RETRIEVE_KNOWLEDGE_BASE_ID` menjadi `KNOWLEDGE_BASE_ID`
+ `ENV_RETRIEVE_MIN_SCORE` menjadi `MIN_SCORE`
**Bagian parameter model lanjutan yang menunjukkan konfigurasi ENV\$1RETRIEVE\$1KNOWLEDGE\$1BASE\$1ID**
![\[parameter model env vars\]](http://docs.aws.amazon.com/id_id/solutions/latest/generative-ai-application-builder-on-aws/images/model-parameters-env-vars.png)
Lihat dokumentasi atau kode sumber alat khusus untuk mengidentifikasi variabel lingkungan yang diperlukan. Untuk alat pengambilan, Anda dapat menemukan opsi konfigurasi di [kode sumber](https://github.com/strands-agents/tools/blob/main/src/strands_tools/retrieve.py#L293).
### Langkah 4: Tambahkan izin IAM
Tambahkan izin IAM yang diperlukan secara manual ke peran eksekusi AgentCore Runtime Anda untuk memungkinkan agen menggunakan alat ini.
Misalnya, untuk menggunakan alat pengambilan dengan Pangkalan Pengetahuan Amazon Bedrock:
1. Arahkan ke konsol IAM di akun AWS Anda.
1. Temukan peran eksekusi AgentCore Runtime untuk agen Anda.
1. Tambahkan izin berikut:
```
{
"Effect": "Allow",
"Action": "bedrock:Retrieve",
"Resource": "arn:aws:bedrock:region:account-id:knowledge-base/knowledge-base-id"
}
```
**Konsol IAM yang menampilkan StrandsRetrieveTool KBAccess kebijakan yang dilampirkan pada peran eksekusi AgentCore Runtime**
![\[pembaruan peran eksekusi agen IAM\]](http://docs.aws.amazon.com/id_id/solutions/latest/generative-ai-application-builder-on-aws/images/agent-execution-role-update-IAM.png)
Izin khusus yang diperlukan akan bervariasi berdasarkan alat. Lihat dokumentasi alat dan dokumentasi layanan AWS untuk menentukan izin IAM yang sesuai.
### Langkah 5: Uji agen
Setelah menyelesaikan langkah-langkah konfigurasi, uji agen Anda untuk memverifikasi alat berfungsi dengan benar. Anda akan melihat pemanggilan alat di log eksekusi dan tanggapan agen.
**Agen berhasil menggunakan alat pengambilan untuk menjawab pertanyaan tentang taman skate**
![\[untaian mengambil contoh alat\]](http://docs.aws.amazon.com/id_id/solutions/latest/generative-ai-application-builder-on-aws/images/strands-retrieve-tool-example.png)
**catatan**
Untuk daftar lengkap alat Strands yang tersedia dan kemampuannya, lihat [dokumentasi Strands Community Tools](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/tools/community-tools-package/).
## Memperluas basis pengetahuan yang didukung dan jenis memori percakapan
Untuk menambahkan implementasi memori percakapan atau basis pengetahuan Anda, tambahkan implementasi yang diperlukan di `shared` folder dan kemudian edit pabrik dan pencacahan yang sesuai untuk membuat instance kelas ini.
Saat Anda menyediakan konfigurasi LLM, yang disimpan di dalam penyimpanan parameter, memori percakapan dan basis pengetahuan yang sesuai akan dibuat untuk LLM Anda. Misalnya, ketika `ConversationMemoryType` ditentukan sebagai DynamoDB, sebuah instance `DynamoDBChatMessageHistory` dari (tersedia `shared_components/memory/ddb_enhanced_message_history.py` di dalam) dibuat. Ketika `KnowledgeBaseType` ditentukan sebagai Amazon Kendra, instance `KendraKnowledgeBase` (tersedia di dalam`shared_components/knowledge/kendra_knowledge_base.py`) dibuat.
## Membangun dan menerapkan perubahan kode
Bangun program dengan `npm run build` perintah. Setelah kesalahan diselesaikan, jalankan `cdk synth` untuk menghasilkan file template dan semua aset Lambda.
1. Anda dapat menggunakan `0/stage-assets.sh` skrip untuk secara manual mementaskan aset apa pun yang dihasilkan ke bucket staging di akun Anda.
1. Gunakan perintah berikut untuk menyebarkan atau memperbarui platform:
```
cdk deploy DeploymentPlatformStack --parameters AdminUserEmail='admin-email@amazon.com'
```
CloudFormation Parameter AWS tambahan apa pun juga harus disertakan bersama dengan **AdminUserEmail**parameternya.