gabrielmoreira 測試課程範例
驗證課堂筆記本和程式碼範例是否能夠在實際運行的
Microsoft Foundry / Azure OpenAI 環境中執行。此版本庫附帶一個執行器
scripts/validate-notebooks.ps1，
可無頭方式執行所有 Python 筆記本並列印出 PASS/FAIL 矩陣。
什麼時候使用
- 「驗證所有筆記本 / 範例是否與我的 Azure 訂閱相容。」
- 「在升級套件或更換模型後做煙霧測試課程。」
- 「哪些課程仍然通過 / 失敗？」
請勿將此用於 AI Smoke Test GitHub Action（該動作驗證已部署
的主機代理 — 請參考 tests/README.md）。這個功能
是在本機運行筆記本。
前置條件（先檢查）
- Python 3.12+ 且安裝課程依賴：
python -m pip install -r requirements.txt以及執行器：python -m pip install nbconvert ipykernel。 - 倉庫根目錄要有
.env（從.env.example複製）且至少包含：AZURE_AI_PROJECT_ENDPOINT— Foundry 專案端點 (https://<account>.services.ai.azure.com/api/projects/<project>)AZURE_AI_MODEL_DEPLOYMENT_NAME— 一個未過時的部署（例如gpt-5-mini）AZURE_OPENAI_ENDPOINT(https://<account>.openai.azure.com) 和AZURE_OPENAI_DEPLOYMENT給直接呼叫 Azure OpenAI 的課程（例如課程 06、02-azure-openai、14 handoff/human-loop）。
- 已完成
az login— 範例以AzureCliCredential認證（Entra ID，免金鑰）。 - 確認模型部署存在：
az cognitiveservices account deployment list -g <rg> -n <account> -o table。
執行驗證
# 所有 Python 筆記本（跳過 .NET、.venv、site-packages、翻譯、技能資產）
pwsh scripts/validate-notebooks.ps1
# 單一課程，每個單元格有較長的超時時間
pwsh scripts/validate-notebooks.ps1 -Filter '08-*' -Timeout 600
# 僅列出會執行的內容（不執行）
pwsh scripts/validate-notebooks.ps1 -List
# 明確指定直譯器（如果 PATH 中沒有 `python`，例如 Windows Store 別名）
pwsh scripts/validate-notebooks.ps1 -Python "C:/path/to/python.exe"
腳本會將執行過的複本、每支筆記本的日誌及 results.json
寫入 $env:TEMP\aiab-nbval，並以失敗數目作為退出碼。
短暫失敗（共享訂閱的 HTTP 429 限流，偶爾的
AzureCliCredential 令牌異常，或逾時）會自動重試
（-Retries，預設 2 次，搭配 -RetryDelaySeconds 延遲，預設 20 秒）。如果某個
模型部署經常遇到 429，請檢查訂閱的 GlobalStandard
TPM 配額（az cognitiveservices usage list -l <region>）——提升單一
部署容量不會有用，因為是整個訂閱配額用盡了。
解讀結果
PASS— 筆記本從頭到尾執行完成，無任何儲存格錯誤。FAIL— 顯示第一個*Error/*Exception行；請開啟輸出目錄中的對應log_*.txt查看完整追蹤紀錄。- 單支筆記本失敗由
-Timeout（每儲存格）限制，因此人機交互儲存格當掛起 時會呈現StdinNotImplementedError，而非無限掛起。
需要額外資源的課程（若無資源則預期失敗）
| 課堂 | 額外需求 |
|---|---|
| 05 Agentic RAG | Azure AI Search（AZURE_SEARCH_SERVICE_ENDPOINT、金鑰）— 有記憶體內備用方案 |
| 11 MCP / GitHub | GitHub MCP 伺服器加 PAT |
| 13 memory (cognee) | 已設定具有模型供應商的 cognee |
| 15 browser-use | 安裝 Playwright 瀏覽器（playwright install）＋ AZURE_OPENAI_CHAT_DEPLOYMENT_NAME |
| 17 local agent | Foundry Local 運行環境＋已下載的 Qwen 模型（本機裝置，無雲端） |
*-dotnet-* 筆記本 |
.NET Interactive kernel（預設排除，使用 -IncludeDotnet） |
回報結果
彙整為按課堂分組的 PASS/FAIL 表格。將真正的回歸問題
（需修正的程式碼或配置錯誤）與環境缺項（缺少 Search/Foundry Local/PAT）分開，
並為每個實際失敗引用其失敗的 log_*.txt。
免責聲明： 本文件使用 AI 翻譯服務 Co-op Translator 進行翻譯。雖然我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於重要資訊，建議尋求專業人工翻譯。我們不對因使用本翻譯而引起的任何誤解或曲解承擔責任。