# 港務公司AI應用Workshop

**建議瀏覽器**
Chrome, Edge

**Workshop 材料連結**
Workshop 實驗環境連結:
- Team 1:https://catalog.us-east-1.prod.workshops.aws/join?access-code=9149-1d168c-2d
- Team 2:https://catalog.us-east-1.prod.workshops.aws/join?access-code=19f1-1c7752-f0
- Team 3:https://catalog.us-east-1.prod.workshops.aws/join?access-code=23d4-1b4ec9-bc
- Team 4:https://catalog.us-east-1.prod.workshops.aws/join?access-code=938a-1f76fa-a5
- Team 5:https://catalog.us-east-1.prod.workshops.aws/join?access-code=a9b7-19168b-de

測試檔案材料連結:
https://drive.google.com/drive/folders/1ymPFrBRlFdVEkgsJ_kTiPdVsS6Q55HZp

**實作課程流程**
1. 實驗環境準備
* 使用 AWS 練習環境
2. 測試檔案與聊天 - Quick Chat Agent
3. 測試檔案與自動化 - Quick Automate

## 實驗目標：
了解AWS AI平台- QuickSuite的使用方式與AI問題拆解工具

## 1. 實驗環境準備
### 1.1 使用 AWS 練習環境

進入課程提供的 AWS Workshop Studio 網址，並點擊 「Email one-time password (OTP)」，以獲得一次性臨時密碼。

輸入自己的 Email 以用於接收一次性臨時密碼 ，並點擊 「傳送密碼」。

>[!Note]
活動期間使用相同 Email 進行登入將會使用相同的練習環境

進入自己的 Email 以取得 9 碼 Passcode。

將 9 碼 Passcode 填入，並點擊 「登入」。

登入並進行環境使用要求條款後，請勾選 「I agree with the Terms and Conditions」，並點擊 「Join event」。

點擊 「Open AWS console」，以開啟 AWS Management Console。

>[!Note]
練習過程中，若 AWS Management Console 逾時登出，可再次點擊此連結以重新登入並更新憑證

進入 AWS Management Console 後，即完成登入。

於搜尋匡搜尋 "QuickSuite"，點擊後開始使用

## 2. 測試檔案與聊天 - Quick Chat Agent
### 2-1. 結果預覽
使用者可上傳檔案，詢問：“整理不同單位/評審對於台中港容積的意見，列出是誰跟意見摘要跟正反性質”，並由AI整理出摘要。

### 2-2. 步驟
1. 於 Quick Suite右側，可直接詢問資料、上傳檔案、或允許搜尋網際網路資料

2. 點擊迴紋針圖示，上傳 差別容積說明書(定稿)by中分.pdf
3. 輸入 "整理不同單位/評審對於台中港容積的意見，列出是誰跟意見摘要跟正反性質”，並由AI整理出摘要"
4. 即可查看結果

### 2-3. 自行設定Agent
1. 點擊 聊天代理程式 > 建立聊天代理程式
2. 先點擊 略過。我們會逐一檢視。一個好的提示(Prompt)，應包含：
a. 角色
b. 目的
c. 功能
d. 語氣風格
3. 輸入以下資訊：
a. 身份：專業的港務法規與業務人員
b. 角色指示：你會根據使用者的問題，查詢相關檔案中是否有可以回答的佐證。你需要列出佐證段落。如果有不清楚的，可以跟使用者互動，得到必要資訊。如果你自己作了假設，也列出重要的假設。
c. 參考文件：上傳文件。可上傳最多十份，共計50MB，不超過100k字之文件
i. 交通部航港局經管公有財產提供商港經營事業機構使用辦法(1010810訂定).pdf
ii. 檔案2-內控自評作業_承辦人_高分業務處.pdf
d. 將名稱從Untitled改為 港務公司業務助手
4. 點擊 啟動聊天代理程式。選擇 一般知識
5. Example:
自評作業需由誰覆核？
Example: 經營機構積欠租金一年，可以提前終止地上權契約嗎？

### 2-4. 使用空間(Space)
您也可以使用預先設定好的知識庫或代理人來直接操作。
在選單中，點擊下拉箭頭，並選擇新增 > 空間 > 業務處知識庫


即可進行問答。

## 3. 測試檔案與自動化 - Quick Automate
目標：
您的工作流程主要是處理基隆港的貨櫃運送數據。您想自動化分析和彙總Excel中的運送業貨櫃數據。
最終產出：
一個包含所有運送業及其對應貨櫃總數的彙總表，方便進行數據分析和報告製作。
這個自動化流程幫您節省了手動逐一檢查每個工作表並提取數據的時間，特別適合處理包含多個運送業數據的複雜Excel檔案。

### 3-1. 結果預覽

### 3-2. 準備環境
本節於實際環境，應為後台一次性準備工作。
**啟用s3 connector:**
此步驟目的在於讓QuickSuite使用一個IAM角色與權限，存取S3上面的資料
- 到Quick Suite，點擊右上角的人像，點擊 > 管理 Quick Suite
- 
- 點擊 許可> AWS動作
- 
- 5. 點擊 新增動作 > Storage > Amazon S3
a. 名稱: s3 connector
b. 角色: arn:aws:iam::<account_id>:role/WSParticipantRole
c. 使用者: [e-mail]
d. 點擊分享，創建。
- 
- 
- 
**啟用Bedrock Action:**
1. 回到Manage QuickSuite > AWS Actions > 新增動作 > Bedrock Runtime
a. 名稱：bedrockConverse
b. 角色ARN: arn:aws:iam::<account_id>:role/WSParticipantRole
c. 使用者: [e-mail]
d. 點擊分享，創建。
- 
完成後您應該會看到有兩個AWS動作。
-

**將Action授權給Group:**
1. 返回QuickSuite > 專案 > Manage Groups > Create Groups
a. Name: automate1
b. Add actions: s3 action & bedrockConverse
c. Done

- 
- 

**上傳檔案到S3：**
這段未來可以跟IT合作進行自動化串接。目前以手動上傳來測試
3. 取得”附件1-114年9月櫃量(各運送人).xls”。
4. 使用Excel開啟 > 另存新檔 > 檔案格式選為Excel Workbook(.xlsx)。確保新的檔案名稱以xlsx結尾：”附件1-114年9月櫃量(各運送人).xlsx”
a. 檔案位置： https://drive.google.com/drive/folders/1JwP8CMb-484dapR3gyvUFve-ne4gGDZa
i. 附件1-114年9月櫃量(各運送人).xls （記得轉檔）
4. 進入 Amazon S3 服務 > 點擊 建立儲存貯體 (Create bucket)


>[!Tip]
>S3是Simple Storage Service的縮寫，顧名思義，S3是一套關於資料儲存的雲端服務，類似於地端使用的公槽空間。使用S3的價值在於，它提供我們一套完善的資安、資料可用性及資料共享服務，並原生跟其他AWS服務深度整合。S3容量無上限、單一檔案大小最高5TB。 Bucket name需為全球唯一，因此請避免使用相同名稱

>[!Tip]
>AWS account ID是每個aws環境的唯一識別碼。
>

5. 本workshop已預先建立 anycompany-hr-documents-<account_id>-us-east-1，點入即可進行下一步。
[Optional] 如要自行創建，可輸入 workshop-[Account_ID] 作為儲存貯體名稱 (Bucket name)，當中 [Account_ID] 請覆蓋成您所使用的 AWS Account ID。例如：”workshop-182399711234”。完成後請點擊 建立儲存貯體 (Create bucket)
6. 將轉檔後的檔案（附件1-114年9月櫃量(各運送人).xlsx）上傳至建立的 S3 Bucket 中。 (上傳 > 新增檔案)

**創建Excel自動化：**
您的工作流程主要是處理基隆港的貨櫃運送數據，具體流程如下：
處理步驟
1. 下載原始數據 - 從S3下載包含各運送業9月份貨櫃量的Excel檔案
2. AI智能分析 - 使用Amazon Bedrock AI模型分析Excel中的每個工作表
3. 數據提取 - AI從每個分頁中提取兩個關鍵資訊：
o 運送人名稱 (從表格標題中的基隆港運送業裝卸櫃量明細資料後面的文字)
o 總櫃數 (從"總計(不含翻艙)-櫃次"欄位的數值)
4. 數據整理 - 將提取的資訊整理成結構化的表格
5. 生成摘要 - 在Excel中創建新的摘要工作表
6. 輸出結果 - 將處理後的檔案上傳回S3儲存
最終產出
一個包含所有運送業及其對應貨櫃總數的彙總表，方便進行數據分析和報告製作。

- QuickSuite > 快速自動化 > 專案
- Start building > Skip。確認左下角是否有 Amazon S3 及Bedrock
- 以下是每個Action的參數

| 動作 | 參數 | 備註 |
| -------- | -------- | -------- |
| Download file | Q action connector id: s3 action<br> Bucket: "anycompany-hr-documents-<account_id>-us-east-1"<br> Key: "附件1-114年9月櫃量(各運送人).xlsx"<br> Output Variable: s3_handle | 取得Excel表格 |
| Create new table | Column names: ["運送人","數量"]<br>Output Variable: table_1 | 創建一個虛擬表格 |
| Prompt model | Q action connector id: bedrockConverse<br>Model id: "amazon.nova-pro-v1:0"<br><br>User prompt: "從每個sheet中，找出兩個資訊，shipper和sum。shipper:為各個分頁表格上標題中基隆港運送業裝卸櫃量明細資料後面的文字。sum:'總計(不含翻艙)'-'櫃次'的總計(最下方的row)。不是TEU欄位。如果同一個sheet中包含多個表格，則每個都要考慮。回傳為一個list of dictionary。例如：[{'shipper':'a','sum':123}]。不要回傳任何其它的東西，僅需回傳該list of dictionary就好。不要用tick(\`\`\`\`\`\`)包含他，也不要聲明他是json(不要\`\`\`json)。"<br><br>Attachments: [s3_handle]<br>Output Variable: result | 透過Bedrock分析Excel表格 |
| Write log message | result | |
| Custom code block | Function Edit:<br>Parameter: json_text<br>\`\`\`<br>return json.loads(json_text.replace("'",'"'))<br>\`\`\`<br><br>json_text: result["text"]<br><br>Return value: result_json | 格式整理 |
| Assign excel scope||
| Open existing workbook | File: s3_handle<br>Output Variable: excel_handle | |
| Loop through items | Collection of items: result_json<br>Item reference: item | |
| : Add new row | Table: table_1<br>Row values: [item["shipper"],item["sum"]]<br>Output variable: table_1 | 將Bedrock結果逐筆寫入虛擬表格 |
| Create new sheet | Workbook identifier: excel_handle<br>Sheet name: "summary_sheet" | |
| Write to sheet | Workbook identifier: excel_handle<br>Sheet name: "summary_sheet"<br>Start at cell: "A1"<br>Data table: table_1<br>Include headers: v | 將虛擬表格寫入Excel |
| Save workbook | Resource id: excel_handle<br>Path: "output_excel.xlsx"<br>Output Variable: output_handle | |
| Upload file | Q action connector id: s3 action<br>File: output_handle<br>Bucket: "anycompany-hr-documents-<account_id>-us-east-1"<br><br><br>Key: "附件1-114年9月櫃量(各運送人)-output.xlsx" | 將檔案上傳回s3 |

>[!Tip]
>備註說明：
Quick Automate的參數使用的是Python格式。因此，對於輸入的參數：
- 未加引號為variable
- 加引號為字串常數
- 如要動態結合，可用f-string
4. 點選 Run，可觀察執行效果
5. 執行結束後，回到AWS Console > S3 > Bucket > 點選檔案 > 下載 。可檢查執行結果