Szybki przewodnik: analizowanie dokumentu przy użyciu CLI usługi Content Understanding

W tym przewodniku Szybki start użyjesz interfejsu wiersza polecenia (azd ai cu) dla usługi Azure Content Understanding w narzędziach Foundry, aby wyodrębnić tekst i układ dokumentu. Analizujesz przykładową fakturę prebuilt-layout i zapisujesz wynik w formacie Markdown lub JSON.

Important

Interfejs wiersza polecenia jest w wersji zapoznawczej. Wersje zapoznawcze są udostępniane bez umowy dotyczącej poziomu usług i nie są zalecane w przypadku obciążeń produkcyjnych. Aby uzyskać więcej informacji, zobacz Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.

Interfejs wiersza polecenia domyślnie używa interfejsu API usługi GA 2025-11-01. Status wydania zapoznawczego jest oddzielony od wersji interfejsu API usługi.

Jeśli nie masz subskrypcji platformy Azure, utwórz je bezpłatnie.

Prerequisites

Polecenia w tym przewodniku Szybki start działają w programie Bash i programie PowerShell. Nie potrzebujesz Python, zestawu SDK języka ani zainicjowanego azd projektu. Analizator prebuilt-layout nie wymaga wdrożeń modelu języka ani wdrożeń modeli osadzania.

Zainstaluj rozszerzenie Content Understanding

Upewnij się, że azd jest to wersja 1.37.0 lub nowsza, a następnie zainstaluj rozszerzenie Content Understanding i sprawdź jego wersję:

azd version
azd ext install azure.ai.content-understanding
azd ai cu version

Odwołanie:azd version, extension commands.

Ostatnie polecenie wyświetla identyfikator rozszerzenia i zainstalowaną wersję, podobnie jak w tym przykładzie. Twoja wersja może się różnić:

azure.ai.content-understanding 0.1.0-preview

Połącz się z Twoim zasobem

Skopiuj punkt końcowy zasobu z portalu Azure. Użyj punktu końcowego zasobu, takiego jak https://<resource-name>.services.ai.azure.com/, a nie adres URL projektu Foundry.

Jeśli masz już zapisany punkt końcowy, zanotuj jego wartość azd ai cu config get CU_ENDPOINT przed jego zastąpieniem.

Zaloguj się, zapisz punkt końcowy jako domyślne ustawienie użytkownika CLI i sprawdź połączenie. Zastąp <your-resource-endpoint> swoim punktem końcowym:

azd auth login
azd ai cu config set CU_ENDPOINT "<your-resource-endpoint>"
azd ai cu doctor

Odwołanie:Nawiązywanie połączenia z usługą Microsoft Foundry i sprawdzanie konfiguracji.

Zapisany endpoint jest dostępny w przyszłych sesjach bez azd init. Zmienne powłoki i odpowiednie azd ustawienia środowiska mają pierwszeństwo przed tym zapisanym ustawieniem domyślnym. Raport doctor przedstawia obowiązujące ustawienia i ich źródła.

Przed kontynuowaniem rozwiąż wszelkie błędy uwierzytelniania lub dostępu do zasobów. Ostrzeżenie dotyczące brakujących wartości domyślnych modelu generowania nie uniemożliwia korzystania z elementu prebuilt-layout.

Interfejs wiersza polecenia używa uwierzytelniania Microsoft Entra ID za pośrednictwem azd. Uwierzytelnianie za pomocą klucza interfejsu API nie jest obsługiwane.

Pobieranie przykładu

W katalogu zapisywalnym pobierz przykładową fakturę za pomocą polecenia powłoki. Uruchom pozostałe polecenia z tego katalogu.

$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

Możesz również pobrać przykładową fakturę w przeglądarce. Zapisz to jako invoice.pdf w katalogu roboczym.

Analizowanie dokumentu

Jeśli nie skonfigurujesz analizatora domyślnego, CLI używa prebuilt-layout do wyodrębniania tekstu i układu dokumentu. To polecenie przekazuje przykład do skonfigurowanego zasobu Azure i może naliczać opłaty:

azd ai cu analyze invoice.pdf

Polecenie wyświetla metadane wstępne YAML, po których następuje wyodrębniony dokument Markdown. Skrócony wynik wygląda następująco:

---
mimeType: application/pdf
pages: 1
---
<!-- InputPageNumber: 1 -->

CONTOSO LTD.


# INVOICE

W terminalu zostanie wyświetlony kod źródłowy Markdown. Tabele mogą być wyświetlane jako HTML; użyj podglądu Markdown, aby wyświetlić zapisaną zawartość.

Użyj --analyzer <analyzer-id> (lub -a), aby zastąpić wartość domyślną dla jednego polecenia. Aby zmienić zapisaną wartość domyślną, uruchom polecenie azd ai cu config set CU_DEFAULT_ANALYZER "<analyzer-id>".

Zapisz wynik

Wybierz pozycję Markdown do odczytu lub JSON, aby uzyskać pełną odpowiedź usługi. Każde polecenie uruchamia nową analizę, która może spowodować naliczanie opłat. Żadne polecenie nie eksportuje poprzedniego wyniku.

Markdown

Aby zapisać metadane wstępne YAML i dokument Markdown, uruchom polecenie:

azd ai cu analyze invoice.pdf --analyzer prebuilt-layout --output-file out.md

JSON

Użyj --output json (lub -o json) dla pełnej odpowiedzi usługi:

azd ai cu analyze invoice.pdf -a prebuilt-layout -o json --output-file out.json

W przypadku obu formatów terminal raportuje dane wejściowe, stan i ścieżkę wyjściową. Otwórz out.md lub out.json, aby sprawdzić zapisaną zawartość.

W odpowiedzi JSON dokument Markdown znajduje się w result.contents[0].markdown. Odpowiedź zawiera również szczegóły układu i może zawierać ostrzeżenia dotyczące usługi oraz informacje o użyciu. Samo rozszerzenie nazwy pliku nie wybiera formatu wyjściowego.

Troubleshooting

Zgłoszenie Resolution
azd ai cu nie jest niedostępna Sprawdź, czy azd ma wersję 1.37.0 lub nowszą oraz czy zainstalowano azure.ai.content-understanding.
Błędy uwierzytelniania lub dostępu do zasobów Uruchom polecenie azd auth login i upewnij się, że zalogowana tożsamość ma dostęp do płaszczyzny danych usługi Content Understanding w zasobie.
doctor zgłasza brakujące domyślne ustawienia modelu generatywnego Kontynuuj za pomocą prebuilt-layout. Przed użyciem analizatorów, które wymagają modeli generatywnych, postępuj zgodnie z przewodnikiem konfiguracji modelu CLI.
The CU endpoint must be a resource URL, not an operation URL Użyj punktu końcowego zasobu, takiego jak https://<resource-name>.services.ai.azure.com/, a nie adresu URL projektu Foundry ani operacji interfejsu API.
Polecenie używa innego zasobu niż oczekiwano Sprawdź efektywny punkt końcowy i jego źródło w doctor raporcie. Zmienna powłoki CU_ENDPOINT lub odpowiednia zmienna środowiskowa azd mogą zastąpić zapisaną wartość domyślną użytkownika.
An input path does not exist or could not be resolved Uruchom polecenie z katalogu zawierającego invoice.pdf lub przekaż poprawną ścieżkę ujętą w cudzysłów do pobranego pliku.
A result file already exists Użyj nowej nazwy pliku wyjściowego. Dodaj --on-existing skip, aby zachować poprzedni wynik bez ponownego analizowania go. Użyj --on-existing reanalyze tylko, aby przesłać kolejne żądanie i zastąpić ten wynik.

Uprzątnij zasoby

Ten przewodnik Szybki start używa istniejącego zasobu i nie tworzy zasobów platformy Azure. Jeśli zastąpisz istniejącą wartość domyślną użytkownika, przywróć jej poprzednią wartość za pomocą azd ai cu config set CU_ENDPOINT "<previous-resource-endpoint>", zamiast ją usuwać.

Jeśli punkt końcowy został zapisany tylko dla tego przewodnika szybkiego startu, opcjonalnie usuń go:

azd ai cu config unset CU_ENDPOINT

Odsyłacz:konfiguracja interfejsu wiersza polecenia.

To polecenie powoduje usunięcie tylko domyślnego ustawienia użytkownika. Nie usuwa zmiennych powłoki ani ustawień w środowiskach projektowych azd.

Usuń lokalne pliki przykładów i wyników, jeśli nie są już potrzebne.

Treści powiązane

  • Ostatnia aktualizacja o