View a markdown version of this page

Referensi API - Pembuat Aplikasi AI Generatif di AWS
Dasbor penyebaranKasus Penggunaan Bersama APIsKasus penggunaan teksKasus penggunaan Agen Batuan Dasar

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Referensi API

Bagian ini menyediakan referensi API untuk solusinya.

Dasbor penyebaran

API REST Metode HTTP Fungsionalitas Penelepon resmi

/deployments

GET

Dapatkan semua penerapan.

Token JWT yang diautentikasi Amazon Cognito

/deployments

POST

Membuat penerapan kasus penggunaan baru.

Token JWT yang diautentikasi Amazon Cognito

/deployments/{useCaseId}

GET

Mendapat detail penerapan untuk satu penerapan.

Token JWT yang diautentikasi Amazon Cognito

/deployments/{useCaseId}

PATCH

Memperbarui penerapan yang diberikan.

Token JWT yang diautentikasi Amazon Cognito

/deployments/{useCaseId}

DELETE

Menghapus penerapan yang diberikan.

Token JWT yang diautentikasi Amazon Cognito

/model-info/use-case-types

GET

Mendapatkan tipe kasus penggunaan yang tersedia untuk penerapan

Token JWT yang diautentikasi Amazon Cognito

/model-info/{useCaseType}/providers

GET

Mendapatkan penyedia model yang tersedia untuk jenis kasus penggunaan yang diberikan

Token JWT yang diautentikasi Amazon Cognito

/model-info/{useCaseType}/{providerName}

GET

Mendapatkan IDs model yang tersedia untuk penyedia tertentu dan tipe kasus penggunaan

Token JWT yang diautentikasi Amazon Cognito

/model-info/{useCaseType}/{providerName}/{modelId}

GET

Mendapat info tentang model yang diberikan, termasuk parameter default.

Token JWT yang diautentikasi Amazon Cognito
catatan

File OpenAPI dan Swagger juga dapat diekspor dari API Gateway untuk integrasi yang lebih mudah dengan API. Lihat Mengekspor REST API dari API Gateway.

POST dan PATCH Muatan

Lihat di bawah untuk contoh muatan POST ke /deployments titik akhir, yang akan membuat kasus penggunaan baru.

{
 "UseCaseName": "usecase1",
 "UseCaseDescription": "Description of the use case to be deployed. For display purposes", // optional
 "DefaultUserEmail": "placeholder@example.com", // optional, if not provided, the Cognito Group and User will not be created
 "DeployUI": true, // optional
 "VpcParams": {
 "VpcEnabled": true,
 "CreateNewVpc": false,
 // provide these if not creating new vpc
 "ExistingVpcId": "vpc-id",
 "ExistingPrivateSubnetIds": ["subnet-1", "subnet-2"],
 "ExistingSecurityGroupIds": ["sg-1", "sg-2"]
 },
 "ConversationMemoryParams": {
 "ConversationMemoryType": "DynamoDB",
 "HumanPrefix": "user", // optional
 "AiPrefix": "ai", // optional
 "ChatHistoryLength": 10 // optional
 },
 "KnowledgeBaseParams": {
 "KnowledgeBaseType": "Bedrock",
 // one of the following based on selected provider
 "BedrockKnowledgeBaseParams": {
 "BedrockKnowledgeBaseId": "my-bedrock-kb",
 "RetrievalFilter": {}, // optional
 "OverrideSearchType": "HYBRID" // optional
 },
 "KendraKnowledgeBaseParams": {
 "AttributeFilter": {}, // optional
 "RoleBasedAccessControlEnabled": true, // optional
 "ExistingKendraIndexId": "12345678-abcd-1234-abcd-1234567890ab",
 // provide the following in place of ExistingKendraIndexId if you want the solution to deploy an index for you
 "KendraIndexName": "index",
 "QueryCapacityUnits": 1, // optional
 "StorageCapacityUnits": 1, // optional
 "KendraIndexEdition": "DEVELOPER" // optional
 },
 "NoDocsFoundResponse": "Sorry, I couldn't find any relevant information for your query.", // optional
 "NumberOfDocs": 3, // optional
 "ScoreThreshold": 0.7, // optional
 "ReturnSourceDocs": true // optional
 },
 "LlmParams": {
 "ModelProvider": "Bedrock | SAGEMAKER",
 // one of the following based on selected provider
 "BedrockLlmParams": {
 "ModelId": "model-id", // use this for on demand models. Can't use with ModelArn
 "ModelArn": "model-arn", // use this for provisioned/custom models. Can't use with ModelId,
 "InferenceProfileId": "profile-id"
 "GuardrailIdentifier": "arn:aws:bedrock:us-east-1:123456789012:guardrail/my-guardrail", // optional
 "GuardrailVersion": "1" // optional. Required if GuardrailIdentifier provided.
 },
 "SageMakerLlmParams": {
 "EndpointName": "some-endpoint",
 "ModelInputPayloadSchema": {},
 "ModelOutputJSONPath": "$."
 },
 // optional. Passes on arbitrary params to the underlying LLM.
 "ModelParams": {
 "param1": {
 "Value": "value1",
 "Type": "string"
 },
 "param2": {
 "Value": 1,
 "Type": "integer"
 }
 },
 // optional
 "PromptParams": {
 "PromptTemplate": "some template",
 "UserPromptEditingEnabled": true,
 "MaxPromptTemplateLength": 1000,
 "MaxInputTextLength": 1000,
 "DisambiguationPromptTemplate": "some disambiguation template",
 "DisambiguationEnabled": true
 },
 "Temperature": 1.0, // optional
 "Streaming": true, // optional
 "RAGEnabled": true, // optional. Must be true if providing KnowledgeBaseParams above.
 "Verbose": false // optional
 },
 "AgentParams": {
 "AgentType": "Bedrock",
 "BedrockAgentParams": {
 "AgentId": "agent-id",
 "AgentAliasId": "alias-id",
 "EnableTrace": true
 }
 },
 // optional
 "AuthenticationParams": {
 "AuthenticationProvider": "Cognito",
 "CognitoParams": {
 "ExistingUserPoolId": "user-pool-id",
 "ExistingUserPoolClientId": "client-id" // optional. If not provided, the solution will create a client for you in the provided pool
 }
 }

}

Untuk pembaruan, strukturnya sama seperti di atas dengan beberapa peringatan:

  • Nama use case tidak dapat diubah

  • Kasus penggunaan hanya dapat mengubah grup keamanan dan subnet setelah digunakan di VPC. VPC itu sendiri tidak dapat diubah.

  • Jika indeks Kendra dibuat untuk Anda sebagai basis pengetahuan, Anda tidak dapat mengubah konfigurasi indeks tersebut (misalnya,, KendraIndexName) QueryCapacityUnits

Kasus Penggunaan Bersama APIs

Titik akhir REST API berikut tersedia untuk kasus penggunaan Teks dan Agen Batuan Dasar:

API REST Metode HTTP Fungsionalitas Penelepon resmi

/details/{useCaseConfigKey}

GET

Mendapat detail konfigurasi untuk kasus penggunaan tertentu.

Token JWT yang diautentikasi Amazon Cognito
WebSocket API Fungsionalitas Penelepon resmi

/$connect

Memulai WebSocket koneksi dan mengautentikasi pengguna.

Token JWT yang diautentikasi Amazon Cognito

/$disconnect

Endpoint dipanggil ketika WebSocket koneksi telah terputus.

Token JWT yang diautentikasi Amazon Cognito

Gunakan API Detail Kasus

Titik akhir API detail mengambil informasi tentang kasus penggunaan tertentu:

GET /details/{useCaseConfigKey}

Titik akhir ini mengembalikan detail konfigurasi untuk kasus penggunaan tertentu, termasuk parameter model, setelan basis pengetahuan, dan informasi penerapan lainnya. Ini membutuhkan token JWT yang diautentikasi Amazon Cognito untuk otorisasi.

Kasus penggunaan teks

WebSocket API Fungsionalitas Penelepon resmi

/sendMessage

Mengirim pesan obrolan pengguna ke WebSocket untuk diproses dengan pengalaman LLM yang dikonfigurasi.

Token JWT yang diautentikasi Amazon Cognito
API REST Metode HTTP Fungsionalitas Penelepon resmi

/feedback/{useCaseId}

POST

Mengirimkan umpan balik pengguna untuk kasus penggunaan tertentu.

Token JWT yang diautentikasi Amazon Cognito

Muatan SendMessage

Jika Anda langsung berintegrasi dengan /sendMessage API, Anda harus mematuhi format payload permintaan dan respons berikut.

Minta Muatan 

{
 "action": "sendMessage",
 "question": "the message to send to the api",
 "conversationId": "", // If not provided, a new conversation will be created, with the conversationId returned in the response. All subsequent messages in that conversation (where history is retained), should provide the conversationId there.
 "promptTemplate": "", // Optional. Overrides the configured prompt
 "authToken": "XXXX" // Optional. accessToken from cognito flow. Required for RAG with RBAC
}
Nama Parameter Tipe Deskripsi

aksi

String

Saat ini kami hanya mendukung tindakan “SendMessage” di WebSocket

pertanyaan

String

Masukan pengguna untuk mengirim ke LLM

ConversationID

String

UUID yang mengidentifikasi percakapan. Jika tidak disediakan, percakapan baru akan dibuat, dengan ConversationId dikembalikan dalam respons. Semua pesan berikutnya dalam percakapan itu (di mana Anda history/context ingin disimpan), harus menyediakan ConversationId di sana.

PromptTemplate

String[Opsional]

Mengganti template prompt untuk pesan ini. Jika kosong atau tidak disediakan, akan default ke prompt yang disetel pada waktu penerapan. Harus memiliki placeholder yang tepat yang ditentukan untuk konfigurasi yang diberikan (yaitu {history} dan {input} untuk penerapan AI Sagemaker non-RAG, dengan penambahan {context} jika menggunakan RAG untuk semua penerapan.

AuthToken

String[Opsional]

AccessToken seperti yang diperoleh dari aliran autentikasi cognito. Ini diperlukan saat menjalankan endpoint websocket obrolan yang dikonfigurasi untuk RAG dengan Role Based Access Control (RBAC). Daftar klaim cognito:groups dalam token JWT ini digunakan untuk mengontrol akses ke dokumen dalam indeks Kendra. Parameter ini tidak diperlukan untuk kasus penggunaan non-RAG. Hal ini juga tidak diperlukan untuk kasus penggunaan RAG yang memiliki RBAC dinonaktifkan.

Muatan Respon

Respon Pertanyaan

WebSocket API akan merespons dengan 1 (jika streaming dinonaktifkan) atau banyak (jika streaming diaktifkan) objek JSON terstruktur sebagai berikut untuk setiap kueri.

{
 "data": "some data",
 "conversationId": "id",
}
Nama Parameter Tipe Deskripsi

data

String

Sepotong respons dari LLM jika streaming diaktifkan, atau seluruh respons. Jika menggunakan streaming, respons format ini dengan konten data END_CONVERSATION akan dikirim untuk menunjukkan akhir respons terhadap satu pertanyaan.

ConversationID

String

ID percakapan yang dimiliki oleh respons SourceDocument ini.

Tanggapan Dokumen Sumber

Jika Anda telah mengonfigurasi kasus penggunaan RAG untuk mengembalikan dokumen sumber, Anda juga akan menerima muatan berikut di akhir setiap respons untuk setiap dokumen sumber yang digunakan untuk membuat respons.

{
 "sourceDocument": {
 "excerpt": "some excerpt from the",
 "location": "s3://fake-bucket/test.txt",
 "score": 0.500,
 "document_title": null,
 "document_id": null,
 "additional_attributes": null
 },
 "conversationId": "some-id"
}
Nama Parameter Tipe Deskripsi

kutipan

String

Kutipan dari dokumen sumber.

lokasi

String

Lokasi dokumen sumber. Ini akan tergantung pada sumber data yang digunakan dan jenis basis pengetahuan, tetapi bisa berupa hal-hal seperti s3 URIs atau situs web.

skor

Number | String

Keyakinan bahwa dokumen tersebut sesuai dengan pertanyaan yang diajukan. Ini akan menjadi float dari 0 ke 1 untuk Bedrock, dan string (misalnya TINGGI, RENDAH, dll.) untuk Kendra.

document_title

String

Judul dokumen sumber yang dikembalikan. Hanya tersedia saat menggunakan Kendra.

document_id

String

ID dari dokumen sumber yang dikembalikan. Hanya tersedia saat menggunakan Kendra.

additional_attributes

String

Bidang ini akan berisi semua atribut tambahan pada dokumen yang disesuaikan pada basis pengetahuan Anda saat konsumsi.

ConversationID

String

ID percakapan yang dimiliki oleh respons SourceDocument ini.

Umpan Balik API Payload

Di bawah ini adalah contoh payload POST ke /feedback/{useCaseId} titik akhir, yang akan mengirimkan umpan balik pengguna untuk kasus penggunaan tertentu:

{
  "useCaseRecordKey": "12345678-12345678",
  "conversationId": "12345678-1234-1234-1234-123456789012",
  "messageId": "12345678-1234-1234-1234-123456789012",
  "feedback": "positive",
  "feedbackReason": ["accurate", "helpful"],
  "comment": "This response was very helpful.",
  "rephrasedQuery": "What are the key features of Amazon Bedrock?",
  "sourceDocuments": [
    "s3://bucket-name/document1.pdf",
    "s3://bucket-name/document2.pdf"
  ]
}

Kasus penggunaan Agen Batuan Dasar

WebSocket API Fungsionalitas Penelepon resmi

/invokeAgent

Mengirim pesan pengguna ke WebSocket untuk diproses dengan agen yang dikonfigurasi.

Token JWT yang diautentikasi Amazon Cognito

Muatan InvokeAgent

Jika Anda langsung berintegrasi dengan/invokeAgent API, Anda harus mematuhi format payload permintaan dan respons berikut.

Meminta muatan 

{
"action": "invokeAgent",
"inputText": "User query to the agent",
"conversationId": "", // Optional. Empty conversationId implies a new conversation. When not provided, a new conversationId will be created and returned with the response. All subsequent messages in the same conversation should provide the same conversationId (i.e. chat memory/history is maintained).
"authToken": "XXXX" // Optional. accessToken from cognito flow. If provided, it needs to be a valid JWT token associated with the user
}
Nama parameter Tipe Deskripsi

aksi

String

Kami hanya mendukung invokeAgent aksi di WebSocket.

InputTeks

String

Masukan pengguna untuk dikirim ke LLM.

ConversationID

String[Optional]

UUID yang secara unik mengidentifikasi percakapan. Jika Anda tidak memberikan nilai ini, solusi akan membuat percakapan baru dan menampilkan ConversationId dalam respons. Semua pesan berikutnya dalam percakapan itu (di mana Anda ingin menyimpan riwayat dan konteks) menyediakan ConversationId di sana.

AuthToken

String[Optional]

AccessToken seperti yang diperoleh dari aliran autentikasi Amazon Cognito. Parameter ini tidak diperlukan. Jika Anda memberikannya, token JWT akan divalidasi. Ini membantu mempermudah solusi ini untuk diperpanjang.

Muatan respons

Tanggapan pertanyaan

WebSocket API akan merespons dengan satu (jika streaming dinonaktifkan) atau banyak (jika streaming diaktifkan) objek JSON terstruktur sebagai berikut untuk setiap kueri.

{
 "data" "some data",
 "conversationId": "id",
 }
Nama parameter Tipe Deskripsi

data

String

Tanggapan dari doa agen.

ConversationID

String

ID percakapan.