本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon Bedrock 知識庫建置 RAG 應用程式
許多企業在其 NFS 和 SMB 檔案共享上累積大型文件儲存庫：產品手冊、政策文件、合約、研究報告、工程規格和使用者產生的內容。
將 Amazon S3 存取點連接到 FSx for ONTAP 磁碟區後，Amazon Bedrock 知識庫會直接從磁碟區擷取內容。基礎模型回應是以您的團隊透過 NFS 或 SMB 儲存它們的文件中為基礎。撰寫者在共享上更新的內容會在下次同步時提供給知識庫。
在本教學課程中，您會透過 Amazon S3 存取點將一組範例 PDFs上傳至 FSx for ONTAP 磁碟區、建立指向存取點的 Amazon Bedrock 知識庫、擷取文件，以及透過 `RetrieveAndGenerate` API 執行問題。
**注意**
本教學課程約需 **35 到 45 分鐘**完成。 AWS 服務 使用的 會針對您建立的資源產生費用。如果您立即完成所有步驟，包括**清除**區段，美國東部 （維吉尼亞北部） 的預期成本不到 **1 美元**。 AWS 區域此預估不包含 FSx for ONTAP 磁碟區本身的持續費用。
## 先決條件
開始前，請確定您具有下列項目：
+ 連接 Amazon S3 存取點的 FSx for ONTAP 磁碟區。存取點必須具有**網際網路**原始伺服器，以便 Amazon Bedrock 服務可以連接它。如需建立存取點的說明，請參閱[建立存取點](fsxn-creating-access-points.md)。
+ 針對 Amazon Bedrock 知識庫支援的內嵌模型以及 AWS 區域 您將建立知識庫的 中至少一個文字產生模型 （例如，`amazon.nova-lite-v1:0`) 啟用模型存取。本教學課程使用 `amazon.titan-embed-text-v2:0`(1024 維度） 做為內嵌模型；也支援 Cohere Embed 模型。如果您選擇不同的內嵌模型，請調整步驟 2 中的向量索引維度，以符合模型的輸出維度。模型存取是在 Amazon Bedrock 主控台的**模型存取**下啟用。如需詳細資訊，請參閱《[Amazon Bedrock 使用者指南》中的存取 Amazon Bedrock 基礎模型](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html)。 **
+ AWS CLI 第 2 版安裝並設定了可建立 IAM 角色、Amazon S3 Vectors 資源和 Amazon Bedrock 知識庫的登入資料。
## 步驟 1：將範例文件上傳至存取點
下載一些公有 PDFs 做為範例 corpus，然後使用 Amazon S3 存取點別名將其上傳到您的存取點。
1. 建立本機目錄並下載範例 PDFs。
```
$ mkdir -p ~/kb-pdfs && cd ~/kb-pdfs
curl -sSL -o aws-overview.pdf https://d1.awsstatic.com/whitepapers/aws-overview.pdf
curl -sSL -o wellarchitected-framework.pdf https://docs.aws.amazon.com/pdfs/wellarchitected/latest/framework/wellarchitected-framework.pdf
curl -sSL -o s3-userguide.pdf https://docs.aws.amazon.com/pdfs/AmazonS3/latest/userguide/s3-userguide.pdf
```
1. 將每個檔案上傳至存取點。將{{access-point-alias}}取代為您的存取點別名 （例如 `my-kb-ap-a1b2c3d4e5f6g7h8i9j0kl1mnop2uuse1a-ext-s3alias`)。您可以在 Amazon FSx 主控台中找到磁碟區**連接的 Amazon S3 存取點**下的別名，或執行 `aws fsx describe-s3-access-point-attachments`。
```
$ for f in *.pdf; do
aws s3 cp "$f" "s3://{{access-point-alias}}/$f"
done
```
1. 驗證登陸磁碟區的檔案。
```
$ aws s3 ls s3://{{access-point-alias}}/
```
**注意**
Amazon Bedrock 知識庫會強制執行每個文件 50 MB 的檔案大小上限。超過 50 MB 的檔案會在擷取期間略過。
## 步驟 2：建立向量存放區
知識庫會將文件內嵌存放在向量存放區中。Amazon Bedrock 知識庫支援數個向量存放區；本教學課程使用 Amazon S3 向量作為預設值，因為它已針對 RAG 工作負載進行成本最佳化，且需要最少的設定。也支援 Amazon OpenSearch Serverless；如需這些指示，請參閱此步驟結尾的可摺疊區段。
### 使用主控台建立向量存放區
如果您使用主控台在 中建立知識庫[步驟 4：建立知識庫和資料來源](#tutorial-bedrock-kb-create-kb)，請在**向量資料庫步驟中選擇快速建立新的向量存放**區，然後選取 **Amazon S3 向量** （建議） 或 **Amazon OpenSearch Serverless**。 ****Amazon Bedrock 會自動建立向量存放區和所有必要的組態。直接跳到[步驟 3：建立知識庫的 IAM 角色](#tutorial-bedrock-kb-iam-role)。
### 使用 建立 Amazon S3 Vectors 向量存放區 AWS CLI
1. 建立 Amazon S3 向量儲存貯體。向量儲存貯體名稱遵循與標準 Amazon S3 儲存貯體相同的全域唯一性規則。本教學課程使用 `fsxn-kb-vectors`；以唯一名稱取代 。
```
$ aws s3vectors create-vector-bucket --vector-bucket-name fsxn-kb-vectors
```
1. 在儲存貯體中建立向量索引。索引維度必須符合內嵌模型的輸出維度； Titan Text Embeddings v2 輸出 1024 個維度。`nonFilterableMetadataKeys` 設定會將 Bedrock 中繼資料欄位標示為不可篩選，使它們不會超出每個向量 2 KB 的可篩選中繼資料限制。
```
$ aws s3vectors create-index --vector-bucket-name fsxn-kb-vectors \
--index-name bedrock-kb-index \
--dimension 1024 --distance-metric cosine --data-type float32 \
--metadata-configuration '{"nonFilterableMetadataKeys":["AMAZON_BEDROCK_METADATA","AMAZON_BEDROCK_TEXT"]}'
```
在回應`indexArn`中記下 ；您可以在 中使用它[步驟 4：建立知識庫和資料來源](#tutorial-bedrock-kb-create-kb)。
### 替代方案：使用 建立 OpenSearch Service Serverless 向量存放區 AWS CLI
如果您偏好 OpenSearch Service Serverless （適用於更高的queries-per-second、進階搜尋功能或現有的操作熟悉度），請使用下列步驟，而不是上述的 Amazon S3 Vectors 程序。
1. 建立集合的加密和網路安全政策。
```
$ aws opensearchserverless create-security-policy --name kb-enc --type encryption \
--policy '{"Rules":[{"ResourceType":"collection","Resource":["collection/fsxn-kb"]}],"AWSOwnedKey":true}'
aws opensearchserverless create-security-policy --name kb-net --type network \
--policy '[{"Rules":[{"ResourceType":"collection","Resource":["collection/fsxn-kb"]},{"ResourceType":"dashboard","Resource":["collection/fsxn-kb"]}],"AllowFromPublic":true}]'
```
1. 建立資料存取政策，授予知識庫角色和目前使用者讀取和寫入集合的許可。將 {{account-id}} 和 {{current-user}} 取代為您的值。
```
$ aws opensearchserverless create-access-policy --name kb-data --type data --policy '[{
"Rules":[
{"ResourceType":"index","Resource":["index/fsxn-kb/*"],"Permission":["aoss:*"]},
{"ResourceType":"collection","Resource":["collection/fsxn-kb"],"Permission":["aoss:*"]}
],
"Principal":[
"arn:aws:iam::{{account-id}}:role/fsxn-kb-role",
"arn:aws:iam::{{account-id}}:user/{{current-user}}"
]
}]'
```
1. 建立集合並等待其變成 `ACTIVE`。
```
$ aws opensearchserverless create-collection --name fsxn-kb --type VECTORSEARCH
aws opensearchserverless batch-get-collection --names fsxn-kb \
--query 'collectionDetails[0].{status:status,endpoint:collectionEndpoint}'
```
1. 使用具有簽章請求的 Python 指令碼，在集合上建立向量索引。索引必須使用 Amazon Bedrock 知識庫預期的維度 1024 （適用於 Titan Text Embeddings v2) 和欄位名稱。如需完整的指令碼和後續的組態步驟，請參閱《*Amazon Bedrock 使用者指南*》中的[使用 OpenSearch Service Serverless 的先決條件](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-setup-oss.html)。使用步驟 4 中產生的集合 ARN 和索引名稱，類型`storage-configuration`為 `OPENSEARCH_SERVERLESS`。
## 步驟 3：建立知識庫的 IAM 角色
知識庫需要可擔任的 IAM 角色，以叫用內嵌模型、透過 Amazon S3 存取點讀取物件，以及存取向量存放區。以下顯示的政策會授予 Amazon S3 Vectors 向量存放區的存取權。如果您改用 OpenSearch Service Serverless，請將 `S3Vectors`陳述式取代為在集合 ARN `aoss:APIAccessAll` 上授予的陳述式。
### 使用主控台建立角色
當您使用 中的 Amazon Bedrock 主控台建立知識庫時[步驟 4：建立知識庫和資料來源](#tutorial-bedrock-kb-create-kb)，請選擇**建立並使用新的服務角色**。Amazon Bedrock 會建立具有所需信任和許可的角色，範圍限定於您的知識庫、內嵌模型、向量存放區和資料來源。直接跳到[步驟 4：建立知識庫和資料來源](#tutorial-bedrock-kb-create-kb)。
### 使用 建立角色 AWS CLI
1. 將下列信任政策儲存為 `kb-trust-policy.json`。它允許 Amazon Bedrock 擔任該角色。將 {{account-id}} 取代為您的 AWS 帳戶 ID。
```
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Service": "bedrock.amazonaws.com"},
"Action": "sts:AssumeRole",
"Condition": {"StringEquals": {"aws:SourceAccount": "{{account-id}}"}}
}]
}
```
1. 將下列許可政策儲存為 `kb-permissions.json`。它授予內嵌模型、Amazon S3 存取點和向量存放區的存取權。將預留位置取代為您的值。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "FoundationModel",
"Effect": "Allow",
"Action": ["bedrock:InvokeModel"],
"Resource": ["arn:aws:bedrock:{{region}}::foundation-model/amazon.titan-embed-text-v2:0"]
},
{
"Sid": "S3AccessPoint",
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:ListBucket"],
"Resource": [
"arn:aws:s3:{{region}}:{{account-id}}:accesspoint/{{access-point-name}}",
"arn:aws:s3:{{region}}:{{account-id}}:accesspoint/{{access-point-name}}/object/*"
]
},
{
"Sid": "S3Vectors",
"Effect": "Allow",
"Action": [
"s3vectors:GetIndex",
"s3vectors:PutVectors",
"s3vectors:GetVectors",
"s3vectors:ListVectors",
"s3vectors:DeleteVectors",
"s3vectors:QueryVectors"
],
"Resource": [
"arn:aws:s3vectors:{{region}}:{{account-id}}:bucket/fsxn-kb-vectors",
"arn:aws:s3vectors:{{region}}:{{account-id}}:bucket/fsxn-kb-vectors/index/*"
]
}
]
}
```
1. 建立角色並連接許可政策。
```
$ aws iam create-role --role-name fsxn-kb-role \
--assume-role-policy-document file://kb-trust-policy.json
aws iam put-role-policy --role-name fsxn-kb-role --policy-name kb-access \
--policy-document file://kb-permissions.json
```
## 步驟 4：建立知識庫和資料來源
Amazon S3 存取點別名的資料來源點。Amazon Bedrock 知識庫接受存取點別名來取代儲存貯體名稱。
### 使用主控台建立知識庫
1. 開啟位於 [https://console.aws.amazon.com/bedrock/](https://console.aws.amazon.com/bedrock/) 的 Amazon Bedrock 主控台。
1. 在左側導覽窗格中，選擇**知識庫**，然後選擇**建立知識庫**。
1. 在**知識庫詳細資訊**下，輸入名稱 （例如 `fsxn-kb`) 和描述。
1. 在 **IAM 許可**下，選擇**建立並使用新的服務角色**。
1. 針對**資料來源**，選擇 **Amazon S3**，然後選擇**下一步**。
1. 輸入資料來源名稱 （例如 `fsxn-s3ap-source`)。
1. 對於 **S3 URI**，輸入 `s3://` 後面接著您的存取點別名，例如 `s3://my-kb-ap-a1b2c3d4e5f6g7h8i9j0kl1mnop2uuse1a-ext-s3alias`。主控台不會區分儲存貯體名稱和此欄位中的存取點別名；存取點別名會依原狀接受。
1. 選擇**下一步**。
1. 在**內嵌模型**下，選擇 **Titan Text Embeddings v2**。
1. 在**向量資料庫中**，選擇**快速建立新的向量存放**區，然後選取 **Amazon S3 向量**。選擇**下一步**。
1. 檢閱組態，然後選擇**建立知識庫**。知識庫可能需要幾分鐘的時間才能建立。
### 使用 建立知識庫 AWS CLI
1. 建立知識庫。將預留位置取代為您的值。`indexArn` 是您在步驟 2 中建立的 Amazon S3 向量索引的 ARN。
```
$ aws bedrock-agent create-knowledge-base --name fsxn-kb \
--role-arn arn:aws:iam::{{account-id}}:role/fsxn-kb-role \
--knowledge-base-configuration '{
"type":"VECTOR",
"vectorKnowledgeBaseConfiguration":{
"embeddingModelArn":"arn:aws:bedrock:{{region}}::foundation-model/amazon.titan-embed-text-v2:0"
}
}' \
--storage-configuration '{
"type":"S3_VECTORS",
"s3VectorsConfiguration":{
"indexArn":"{{index-arn}}"
}
}'
```
記下回應中的 `knowledgeBaseId`。
1. 建立資料來源。使用 格式，將 Amazon S3 存取點別名做為 `bucketArn` 欄位中的儲存貯體名稱傳遞`arn:aws:s3:::{{access-point-alias}}`。
```
$ aws bedrock-agent create-data-source \
--knowledge-base-id {{knowledge-base-id}} \
--name fsxn-s3ap-source \
--data-source-configuration '{
"type":"S3",
"s3Configuration":{"bucketArn":"arn:aws:s3:::{{access-point-alias}}"}
}'
```
記下回應中的 `dataSourceId`。
## 步驟 5：擷取文件
執行擷取任務，透過存取點編目文件、產生內嵌，並在向量存放區中編製索引。
### 使用主控台執行擷取
1. 在 Amazon Bedrock 主控台中，開啟您的知識庫。
1. 在**資料來源**區段中，選取您的資料來源，然後選擇**同步**。
1. 等待**同步狀態**顯示**就緒**。
### 使用 執行擷取 AWS CLI
1. 啟動擷取任務。
```
$ aws bedrock-agent start-ingestion-job \
--knowledge-base-id {{knowledge-base-id}} \
--data-source-id {{data-source-id}}
```
記下回應中的 `ingestionJobId`。
1. 輪詢任務直到完成。
```
$ aws bedrock-agent get-ingestion-job \
--knowledge-base-id {{knowledge-base-id}} \
--data-source-id {{data-source-id}} \
--ingestion-job-id {{ingestion-job-id}}
```
`status` 欄位會從 轉換為 `IN_PROGRESS` `COMPLETE`。`statistics` 欄位會顯示已掃描和編製索引的文件數量。
## 步驟 6：查詢知識庫
向知識庫詢問以擷取文件中為基礎的問題。回應包含透過 Amazon S3 存取點別名參考來源文件的引文。
### 使用主控台查詢
1. 在 Amazon Bedrock 主控台中，開啟您的知識庫。
1. 選擇**測試知識庫**。
1. 在**產生回應**下，選取文字產生模型 （例如 **Nova Lite**)。
1. 輸入問題，例如 `What are the pillars of the AWS Well-Architected Framework?` ，然後選擇**執行**。答案會顯示引文參考，連結至 Amazon S3 存取點中的來源文件。
### 使用 查詢 AWS CLI
使用 `retrieve-and-generate` 命令。將預留位置取代為您的值。對於您有權存取的文字產生模型， `modelArn` 必須參考推論描述檔。
```
$ aws bedrock-agent-runtime retrieve-and-generate \
--input '{"text":"What are the pillars of the AWS Well-Architected Framework?"}' \
--retrieve-and-generate-configuration '{
"type":"KNOWLEDGE_BASE",
"knowledgeBaseConfiguration":{
"knowledgeBaseId":"{{knowledge-base-id}}",
"modelArn":"arn:aws:bedrock:{{region}}:{{account-id}}:inference-profile/us.amazon.nova-lite-v1:0"
}
}'
```
回應包含 中產生的答案，`output.text`以及`citations`陣列中的引文清單。每個引文都包含 `s3Location.uri` 欄位，透過存取點別名指向來源文件，格式為 `s3://{{access-point-alias}}/{{file.pdf}}`。
## 疑難排解
擷取任務報告檔案被忽略
Amazon Bedrock 知識庫會強制執行每個文件 50 MB 的檔案大小上限。大於 50 MB 的檔案會列在 中`failureReasons`並略過。在上傳之前分割或壓縮大型文件。
`ValidationException`：標記為舊版的模型
您為 帳戶指定的文字產生模型已棄用。選擇作用中的推論設定檔，例如 `us.amazon.nova-lite-v1:0`或其他目前支援的模型。執行 `aws bedrock list-inference-profiles`以列出可用的設定檔。
`AccessDeniedException` 擷取期間
確認知識庫 IAM 角色在存取點 ARN `s3:ListBucket`上具有 `s3:GetObject`和 （而不是基礎磁碟區上），且存取點具有網際網路原始伺服器，以便 Amazon Bedrock 服務可以連接它。如果您在步驟 2 中選擇 OpenSearch Service Serverless 替代方案，也請確認資料存取政策將角色列為委託人。
擷取任務成功，但查詢未傳回任何相關段落
確認向量索引是以 `dimension: 1024`（適用於 Titan Text Embeddings v2) 建立，且索引映射中的欄位名稱符合知識庫上設定的欄位名稱。
## 清除
若要避免持續收費，請刪除您建立的資源：
+ Amazon Bedrock 知識庫和資料來源
+ Amazon S3 向量索引和向量儲存貯體 （如果您在步驟 2 中使用替代項目，則為 OpenSearch Service Serverless 集合）
+ IAM 角色和內嵌政策
+ 上傳至存取點的物件 （如果不再需要）
```
$ aws bedrock-agent delete-data-source --knowledge-base-id {{knowledge-base-id}} --data-source-id {{data-source-id}}
aws bedrock-agent delete-knowledge-base --knowledge-base-id {{knowledge-base-id}}
aws s3vectors delete-index --vector-bucket-name fsxn-kb-vectors --index-name bedrock-kb-index
aws s3vectors delete-vector-bucket --vector-bucket-name fsxn-kb-vectors
aws iam delete-role-policy --role-name fsxn-kb-role --policy-name kb-access
aws iam delete-role --role-name fsxn-kb-role
```
### 替代方案：清除 OpenSearch Service Serverless 資源
如果您在步驟 2 中選擇 OpenSearch Service Serverless 替代方案，請將上述`s3vectors`命令取代為下列命令。閒置 OpenSearch Service Serverless 集合會產生 OCU 小時費用，因此當您完成教學課程時，請立即將其刪除。
```
$ # Get the collection ID (required by delete-collection; the name is not accepted)
COLLECTION_ID=$(aws opensearchserverless batch-get-collection --names fsxn-kb \
--query 'collectionDetails[0].id' --output text)
# Delete the collection, then the policies
aws opensearchserverless delete-collection --id "$COLLECTION_ID"
aws opensearchserverless delete-access-policy --name kb-data --type data
aws opensearchserverless delete-security-policy --name kb-net --type network
aws opensearchserverless delete-security-policy --name kb-enc --type encryption
```