在這個快速入門中,你會使用 Foundry 工具中 Azure 內容理解的 CLIazd ai cu() 來擷取文件文字與版面配置。 您會使用 prebuilt-layout 分析範例發票,並將結果儲存為 Markdown 或 JSON。
Important
CLI 目前還在預覽階段。 預覽版在沒有服務等級協議的情況下提供,且不建議用於生產工作負載。 欲了解更多資訊,請參閱 Microsoft Azure 預覽版補充使用條款。
CLI 預設使用 2025-11-01 GA 服務 API。 其預覽版本狀態與服務 API 版本是分開的。
如果您沒有 Azure 訂用帳戶,請建立免費帳戶。
Prerequisites
-
Azure Developer CLI (
azd) 版本 1.37.0 或更新版本。 - 位於支援的區域中的Microsoft Foundry 資源。
- 該資源上的 認知服務使用者 角色,或等效的資料平面權限。 如有需要,請要求管理員指派此角色。 僅靠貢獻者並不會授予 Content Understanding 資料平面的存取權。
這個快速入門的指令在 Bash 和 PowerShell 中運作。 你不需要 Python、語言 SDK 或已初始化的 azd 專案。
prebuilt-layout 分析器不需要語言或嵌入模型部署。
安裝內容理解擴充功能
確認是 azd 版本 1.37.0 或更新,然後安裝 Content Understanding 擴充功能並檢查其版本:
azd version
azd ext install azure.ai.content-understanding
azd ai cu version
最後一個指令顯示擴充功能 ID 及已安裝版本,類似此範例。 你的版本可能不同:
azure.ai.content-understanding 0.1.0-preview
連線到你的資源
從 Azure 入口複製你的資源端點。 使用資源端點,例如 https://<resource-name>.services.ai.azure.com/,而非 Foundry 專案的 URL。
如果您已有儲存的端點,請在取代之前,先使用 azd ai cu config get CU_ENDPOINT 記下其值。
登入,將端點儲存為 CLI 使用者預設,並檢查連線。 用你的端點替換 <your-resource-endpoint>:
azd auth login
azd ai cu config set CU_ENDPOINT "<your-resource-endpoint>"
azd ai cu doctor
參考資料:連接 Microsoft Foundry 並檢查設定。
儲存的端點可在後續工作階段中使用,無需 azd init。 shell 變數和適用的 azd 環境設定優先於這個儲存的預設值。
doctor報告展示了有效的設定及其來源。
在繼續之前,先解決任何認證或資源存取錯誤。 關於缺少生成模型預設值的警告,並不會阻止你使用 prebuilt-layout。
CLI 透過 azd 使用 Microsoft Entra ID 進行驗證。 不支援 API 金鑰認證。
下載範例
在可寫入的目錄中,使用適用於你的 shell 的指令下載範例發票。 從那個目錄執行剩下的指令。
$sampleRoot = "https://raw.githubusercontent.com/Azure-Samples"
$samplePath = "azure-ai-content-understanding-assets/main/document/invoice.pdf"
Invoke-WebRequest -Uri "$sampleRoot/$samplePath" -OutFile invoice.pdf
你也可以在瀏覽器 下載樣本發票 。 把它存成 invoice.pdf 到你的工作目錄。
分析文件
如果你沒有設定預設分析器,CLI 會用 prebuilt-layout 來擷取文件文字和版面配置。 此指令會將範例上傳至您設定的 Azure 資源,並可能產生費用:
azd ai cu analyze invoice.pdf
指令會顯示 YAML 前置資料,接著是擷取的文件 Markdown。 簡短結果如下:
---
mimeType: application/pdf
pages: 1
---
<!-- InputPageNumber: 1 -->
CONTOSO LTD.
# INVOICE
終端機顯示 Markdown 原始碼。 表格可以以 HTML 形式出現;使用 Markdown 預覽來查看已儲存的內容。
使用 --analyzer <analyzer-id> (或 -a) 來覆蓋某個指令的預設值。 要更改已儲存的預設值,請執行 azd ai cu config set CU_DEFAULT_ANALYZER "<analyzer-id>"。
儲存結果
選擇 Markdown 來閱讀,或選擇 JSON 以取得完整的服務回應。 每個指令都會執行新的分析,可能會產生收費。 這兩個指令都不會匯出之前的結果。
Markdown
若要儲存 YAML 前置中繼資料和文件的 Markdown 內容,請執行:
azd ai cu analyze invoice.pdf --analyzer prebuilt-layout --output-file out.md
JSON
使用 --output json(或 -o json)來取得完整的服務回應:
azd ai cu analyze invoice.pdf -a prebuilt-layout -o json --output-file out.json
無論哪種格式,終端機都會回報輸入、狀態和輸出路徑。 打開 out.md 或 out.json 以檢查已儲存的內容。
在 JSON 回應中,文件 Markdown 位於 result.contents[0].markdown。 回應內容亦包含版面細節,並可能包含服務警告及使用資訊。 僅靠副檔名本身並不會選擇輸出格式。
Troubleshooting
| Issue | Resolution |
|---|---|
azd ai cu 無法使用 |
確認 azd 的版本為 1.37.0 或更新版本,並且 azure.ai.content-understanding 已經安裝好。 |
| 認證或資源存取錯誤 | 執行 azd auth login 並確認登入身份在該資源上擁有內容理解資料平面的存取權限。 |
doctor 回報缺少生成式模型的預設設定 |
繼續使用prebuilt-layout。 在使用需要生成式模型的分析器之前,請遵循 CLI 模型設定指南。 |
The CU endpoint must be a resource URL, not an operation URL |
使用資源端點,例如 https://<resource-name>.services.ai.azure.com/,而非 Foundry 專案或 API 操作 URL。 |
| 指令使用的資源與預期不同 | 在 doctor 報告中,檢查目前生效的端點及其來源。 shell CU_ENDPOINT 變數或適用的 azd 環境可以覆寫已儲存的使用者預設值。 |
An input path does not exist or could not be resolved |
請從包含 invoice.pdf 的目錄執行,或傳入以引號括住的已下載檔案正確路徑。 |
A result file already exists |
使用新的輸出檔名。 新增 --on-existing skip 以保留先前的結果,而不必重新分析。 僅用 --on-existing reanalyze 來提交另一個請求並替換該結果。 |
清理資源
這個快速入門使用現有資源,並不會建立 Azure 資源。 如果你替換了現有的使用者預設值,請使用 azd ai cu config set CU_ENDPOINT "<previous-resource-endpoint>" 還原其先前的值,而不是移除它。
如果你只為這個快速入門儲存端點,請選擇性地移除它:
azd ai cu config unset CU_ENDPOINT
參考資料:CLI 設定。
此指令僅移除使用者預設設定。 這不會清除殼層變數,也不會清除 azd 專案環境中的設定。
如果不再需要,請刪除本地的取樣和結果檔案。