Platform For AI：使用自訂鏡像部署模型服務

步驟一：環境準備

在開始之前，請確保已在同一地區（如杭州）準備好以下環境和資源：

步驟二：檔案準備

登入ECS執行個體，建立一個專案檔夾（例如 my-app），並包含以下三個檔案：

1. requirements.txt （應用依賴）

   flask
   gunicorn

2. app.py（Web應用代碼）

   from flask import Flask
   
   app = Flask(__name__)
   
   @app.route('/hello/model')
   def hello_world():
       # 此處可以整合您的模型推理或其他商務邏輯
       return 'Hello World from Gunicorn!'
   
   # 注意：無需 app.run()，應用將由 Gunicorn 啟動

3. Dockerfile（鏡像構建指令） 

   # 1. 使用輕量級的官方Python鏡像作為基礎
   FROM python:3.9-slim
   
   # 2. 設定工作目錄
   WORKDIR /app
   
   # 3. 複製依賴檔案並安裝，利用Docker緩衝機制加速後續構建
   COPY requirements.txt .
   RUN pip install --no-cache-dir -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
   
   # 4. 複製應用代碼
   COPY app.py .
   
   # 5. 聲明服務連接埠
   EXPOSE 8000
   
   # 6. 定義容器預設啟動命令（可被EAS控制台的“運行命令”覆蓋）
   CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", "app:app"]

步驟三：構建並推送鏡像

1. 開啟終端，進入專案檔夾（my-app）。

2. 登入到您的ACR執行個體。將命令中的預留位置替換為實際資訊。

   說明

   進入ACR鏡像倉庫的詳情頁可擷取登入、拉取推送的命令樣本，注意樣本為公網地址，請修改為內網地址。

   # 樣本： docker login --username=your_user my-registry-vpc.cn-hangzhou.aliyuncs.com
   docker login --username=<使用者名稱> <ACR倉庫內網網域名稱>

3. 構建Docker鏡像並為其打上完整的標籤。

   # 樣本： docker build -t my-registry-vpc.cn-hangzhou.aliyuncs.com/pai-demo/flask-app:v1 .
   # <ACR倉庫內網網域名稱>/<命名空間>/<鏡像倉庫名>:<版本號碼> 即為鏡像地址
   docker build -t <ACR倉庫內網網域名稱>/<命名空間>/<鏡像倉庫名>:<版本號碼> .

4. （推薦）推送前本地驗證鏡像：將鏡像推送到 ACR 之前，建議先在本地運行以下命令驗證鏡像啟動是否正常，避免將問題鏡像推送至倉庫。

   # 將 <連接埠號碼> 替換為 Dockerfile 中 EXPOSE 的連接埠（本樣本為 8000）
   docker run -p <連接埠號碼>:<連接埠號碼> <ACR倉庫內網網域名稱>/<命名空間>/<鏡像倉庫名>:<版本號碼>

   若應用正常響應，則說明鏡像可用，可繼續推送。

5. 將構建好的鏡像推送到ACR。

   # 樣本：docker push my-registry-vpc.cn-hangzhou.aliyuncs.com/pai-demo/flask-app:v1
   docker push <ACR倉庫網域名稱>/<命名空間>/<鏡像倉庫名>:<版本號碼>

步驟四：部署服務

1. 登入PAI控制台，在頁面上方選擇目標地區，並在右側選擇目標工作空間，然後單擊進入EAS。

2. 單擊部署服务，選擇自定义模型部署 > 自定义部署。

3. 配置以下關鍵參數：

   • 部署方式：選擇镜像部署。

   • 镜像配置：選擇镜像地址，填寫上一步中推送的完整鏡像地址，即my-registry-vpc.cn-hangzhou.aliyuncs.com/pai-demo/flask-app:v1。

     由於本樣本使用同一阿里雲帳號下的ACR，EAS可免密拉取鏡像，無需提供使用者名稱和密碼。

   • 运行命令：gunicorn -w 4 -b 0.0.0.0:8000 app:app

     EAS控制台填寫的運行命令會覆蓋 Dockerfile中的CMD指令。建議將啟動命令填寫在此處，便於後續調試和修改。

   • 端口号：8000。

   • 部署资源：本樣本使用CPU資源即可。如選擇公共资源下的ecs.c6.large。

   • 专有网络配置：選擇一個VPC（VPC_HZ）、交換器和安全性群組。

     請確保此處選擇的VPC已在ACR執行個體的“存取控制”中添加，否則將因網路不通導致鏡像拉取失敗（常見錯誤為ImagePullBackOff）。

4. 單擊部署，當服務狀態變為运行中，表示部署成功。

鏡像倉庫類型

EAS部署服務時需要從鏡像倉庫拉取鏡像，推薦使用阿里雲Container RegistryACR儲存鏡像。拉取鏡像時使用VPC地址，以獲得更好的效能和安全性。

鏡像倉庫身份認證

使用需要認證的私人鏡像倉庫，需在服務部署時提供使用者名稱密碼資訊。

在JSON設定檔中通過dockerAuth參數指定認證資訊，值為username:password的Base64編碼形式。

例如，對於abcd:abcde12345，執行命令echo -n "abcd:abcde12345" | base64得到YWJjZDphYmNkZTEy****，即為dockerAuth的取值。

{"dockerAuth": "YWJjZDphYmNkZTEy****"}

Q：鏡像拉取失敗（ImagePullBackOff）

請依次排查：

1. 鏡像地址正確性：請檢查鏡像地址、命名空間和版本號碼（Tag）是否正確，且鏡像已成功推送到倉庫。

2. 系統硬碟空間：如有報錯no space left on device，請擴容系統硬碟。

3. 網路連通性：

   • 使用鏡像公網地址：請確認已為EAS配置能訪問公網的VPC，且為ACR開通公網訪問（跨地區使用公網地址速度特別慢，容易因網路問題失敗）。

   • 使用鏡像內網地址：如果跨地區，僅支援使用ACR企業版，且需打通VPC。詳情請參見跨地區或從IDC訪問ACR企業版執行個體。

4. ACR存取控制：根據使用的鏡像地址類型檢查是否為ACR配置公網的存取控制、配置專用網路的存取控制。

5. 倉庫認證：如果使用需要認證的私人鏡像倉庫（非本帳號下ACR），請檢查在鏡像配置中填寫的認證資訊是否正確。

Q：如何跨地區使用 ACR 鏡像？

EAS服務預設能通過 VPC 內網地址拉取同地區 ACR 倉庫中的鏡像。如果 ACR 執行個體與 EAS 服務不在同一地區，內網直連不可用。可通過以下方法解決：

• 方法一（推薦）：在 EAS 服務所在地區重新建立 ACR 執行個體，將鏡像推送到同地區倉庫後再部署，從根本上避免跨地區問題。

• 方法二：通過 CEN（雲企業網）打通兩個地區的 VPC，實現跨地區內網拉取。具體操作參見跨地區或從IDC訪問企業版執行個體。

• 方法三（測試情境）：通過公網地址拉取鏡像，需確認已為 ACR 開通公網訪問，並為 EAS 服務配置能訪問公網的 NAT Gateway。速度較慢且存在安全風險，僅建議用於測試情境。

Q：部署自訂鏡像報錯"no match for platform in manifest"怎麼辦？

該錯誤表示推送的鏡像架構（如arm64）與 EAS 執行個體的運行環境（通常為amd64/x86_64）不匹配，EAS 無法在該機型上運行此鏡像。常見於在 M 系列晶片 Mac（arm64）上構建鏡像後部署到 EAS（amd64）執行個體的情境。解決方案如下：

1. 確認 EAS 目標執行個體的 CPU 架構（大多數 EAS 執行個體為amd64）。

2. 在本地重新構建與 EAS 執行個體架構匹配的鏡像：

   # 構建 amd64 架構鏡像（適用於大多數EAS執行個體）
   docker build --platform linux/amd64 -t <ACR倉庫網域名稱>/<命名空間>/<鏡像倉庫名>:<版本號碼> .

3. 將新鏡像推送到 ACR 後，重新部署服務。

Q：ACK 能串連EAS專屬鏡像庫（PAI官方鏡像）嗎？

EAS專屬鏡像庫不支援 ACK 直連，ACK 無法直接拉取EAS專屬鏡像庫中的鏡像。