Freigeben über

Azure AI Content Understanding Client-Bibliothek für JavaScript - Version 1.0.0

Azure AI Content Understanding ist ein multimodaler KI-Dienst, der semantische Inhalte aus Dokumenten, Video-, Audio- und Bilddateien extrahiert. Es verwandelt unstrukturierte Inhalte in strukturierte, maschinenlesbare Daten, die für die abrufverstärkte Generierung (RAG) und automatisierte Arbeitsabläufe optimiert sind.

Verwenden Sie die Client-Bibliothek für Azure AI Content Understanding, um:

  • Dokumentinhalte extrahieren – Text, Tabellen, Abbildungen, Layoutinformationen und strukturierte Markdowns aus Dokumenten (PDF, Bilder mit Text oder handgeschriebenem Text, Office-Dokumente und mehr) extrahieren
  • Transkribieren und analysieren Sie Audio – Wandeln Sie Audioinhalte in durchsuchbare Transkripte mit Sprecher-Tagebuch- und Zeitinformationen um
  • Videoinhalte analysieren – Visuelle Bilder extrahieren, Audiospuren transkribieren und strukturierte Zusammenfassungen aus Videodateien erstellen
  • Nutzen Sie vorgefertigte Analysatoren - Verwenden Sie serientaugliche vorgefertigte Analysatoren in verschiedenen Branchen, darunter finance und Steuern (Rechnungen, Belege, Steuerformulare), Identitätsverifizierung (Reisepässe, Führerscheine), Hypotheken und Kreditvergabe (Kreditanträge, Bewertungen), Beschaffung und Verträge (Bestellungen, Verträge) sowie Versorgungsunternehmen (Rechnungsabrechnungen)
  • Erstellen Sie benutzerdefinierte Analysatoren – Bauen Sie domänenspezifische Analysatoren für spezialisierte Inhaltsextraktionsbedürfnisse in allen vier Modalitäten (Dokumente, Video, Audio und Bilder)
  • Dokumente und Videos klassifizieren – Automatisch Dokumente und Videos nach Typ kategorisieren und extrahieren Sie Informationen aus ihnen

Wichtige Links:

Getting started

Derzeit unterstützte Umgebungen

Weitere Details finden Sie in unserer Support-Richtlinie.

Voraussetzungen

Installiere das @azure/ai-content-understanding Paket

Installieren Sie die Client-Bibliothek Azure Content Understanding für JavaScript mit npm:

npm install @azure/ai-content-understanding

Konfigurieren Sie Ihre Microsoft Foundry-Ressource

Bevor Sie das Content Understanding SDK verwenden, müssen Sie eine Microsoft Foundry-Ressource einrichten und die erforderlichen großen Sprachmodelle bereitstellen. Content Understanding verwendet derzeit OpenAI-GPT-Modelle (wie gpt-4.1, gpt-4.1-mini und text-embedding-3-large).

Schritt 1: Microsoft Foundry-Ressource erstellen

Wichtig: Sie müssen Ihre Microsoft Foundry-Ressource in einem Bereich erstellen, der Content Understanding unterstützt. Eine Liste der verfügbaren Regionen finden Sie unter Azure Content Understanding Region und Sprachunterstützung.

  1. Befolgen Sie die Schritte im Azure Content Understanding Quickstart um eine Microsoft Foundry-Ressource im Azure portal zu erstellen
  2. Holen Sie sich die Endpunkt-URL Ihrer Foundry-Ressource von Azure Portal:
    • Geh zu Azure Portal
    • Navigiere zu deiner Microsoft Foundry-Ressource
    • Gehen Sie zu Resource Management>Schlüssel und Endpunkt
    • Kopiere die URL Endpoint (typischerweise https://<your-resource-name>.services.ai.azure.com/)

Wichtig: Erteile erforderliche Berechtigungen

Nachdem Sie Ihre Microsoft Foundry-Ressource erstellt haben, müssen Sie sich die Rolle Cognitive Services User zuweisen, um API-Aufrufe für die Einstellung von Standardmodell-Deployments zu aktivieren:

  1. Geh zu Azure Portal
  2. Navigiere zu deiner Microsoft Foundry-Ressource
  3. Gehe zu Access Control (IAM) im linken Menü
  4. Klicken Sie auf Hinzufügen>Rollenzuweisung hinzufügen
  5. Wählen Sie die Rolle des Nutzers der kognitiven Dienste aus
  6. Weise es dir selbst (oder dem Benutzer/Service-Principal, der die Anwendung ausführen wird) zu

Hinweis: Diese Rollenzuweisung ist erforderlich, selbst wenn du der Eigentümer der Ressource bist. Ohne diese Rolle können Sie die Content Understanding API nicht aufrufen, um Modellbereitstellungen für vorgefertigte Analysatoren zu konfigurieren.

Schritt 2: Bereitstellen Sie erforderliche Modelle ein

Wichtig: Die vorgefertigten und kundenspezifischen Analysatoren erfordern große Sprachmodellbereitstellungen. Sie müssen mindestens diese Modelle bereitstellen, bevor Sie vorgefertigte und benutzerdefinierte Analysatoren verwenden:

  • prebuilt-documentSearch, prebuilt-imageSearch, prebuilt-audioSearch, erfordern prebuilt-videoSearchgpt-4.1-mini und text-embedding-3-large
  • Andere vorgefertigte Analysatoren wie prebuilt-invoice, prebuilt-receipt benötigen gpt-4.1 und text-embedding-3-large

Um ein Modell bereitzustellen:

  1. In Microsoft Foundry gehen Sie zu Deployments>Deploy model>Deploy Base model Deploy
  2. Suchen Sie nach und wählen Sie das Modell aus, das Sie einsetzen möchten. Derzeit benötigen vorgefertigte Analysatoren Modelle wie gpt-4.1, gpt-4.1-mini, und text-embedding-3-large
  3. Schließen Sie die Bereitstellung mit Ihren bevorzugten Einstellungen durch
  4. Beachten Sie den von Ihnen gewählten Deployment-Namen (konventionell verwenden Sie den Modellnamen als Deployment-Name, z. B gpt-4.1 . für das gpt-4.1 Modell)

Wiederholen Sie diesen Vorgang für jedes Modell, das von Ihren vorgefertigten Analysatoren benötigt wird.

Weitere Informationen zum Bereitstellen von Modellen finden Sie unter Create Model Deployments im Microsoft Foundry Portal.

Schritt 3: Modellbereitstellungen konfigurieren (erforderlich für vorgefertigte Analysatoren)

WICHTIG: Dies ist eine einmalige Einrichtung laut Microsoft Foundry-Ressource , die Ihre bereitgestellten Modelle denjenigen zuordnet, die von den vorgefertigten Analysatoren und benutzerdefinierten Modellen benötigt werden. Wenn du mehrere Microsoft Foundry-Ressourcen hast, musst du jede einzeln konfigurieren.

Du musst die Standardmodellzuordnungen in deiner Microsoft Foundry-Ressource konfigurieren. Dies kann programmatisch mit dem SDK durchgeführt werden. Die Konfiguration ordnet Ihre bereitgestellten Modelle (derzeit gpt-4.1, gpt-4.1-mini und text-embedding-3-large) den großen Sprachmodellen zu, die von vorgefertigten Analysatoren benötigt werden.

Um Modellbereitstellungen mithilfe von Code zu konfigurieren, siehe das Update Defaults-Beispiel für ein vollständiges Beispiel. Hier ist ein kurzer Überblick:

import { ContentUnderstandingClient } from "@azure/ai-content-understanding";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = process.env["CONTENTUNDERSTANDING_ENDPOINT"]!;
const client = new ContentUnderstandingClient(endpoint, new DefaultAzureCredential());

// Map your deployed models to the models required by prebuilt analyzers
const updatedDefaults = await client.updateDefaults({
  modelDeployments: {
    "gpt-4.1": process.env["GPT_4_1_DEPLOYMENT"]!,
    "gpt-4.1-mini": process.env["GPT_4_1_MINI_DEPLOYMENT"]!,
    "text-embedding-3-large": process.env["TEXT_EMBEDDING_3_LARGE_DEPLOYMENT"]!,
  },
});

console.log("Model deployments configured successfully!");

Hinweis: Die Konfiguration wird in deiner Microsoft Foundry-Ressource gespeichert, sodass du das nur einmal pro Ressource ausführen musst (oder immer wenn du deine Deployment-Namen änderst).

Authentifizieren des Clients

Um den Client zu authentifizieren, benötigen Sie Ihren Microsoft Foundry Resource Endpoint und die Zugangsdaten. Du kannst entweder einen API-Schlüssel oder eine Microsoft Entra ID-Authentifizierung verwenden.

Verwendung von DefaultAzureCredential

Die einfachste Authentifizierung ist die Verwendung DefaultAzureCredentialvon , das mehrere Authentifizierungsmethoden unterstützt und sowohl in lokalen Entwicklungs- als auch in Produktionsumgebungen gut funktioniert.

Um den unten gezeigten Anbieter DefaultAzureCredential oder andere mit dem Azure SDK bereitgestellte Zugangsdatenanbieter zu verwenden, installieren Sie bitte das @azure/identity-Paket:

npm install @azure/identity

Mithilfe von Node.js- und Node-ähnlichen Umgebungen können Sie die DefaultAzureCredential Klasse verwenden, um den Client zu authentifizieren.

import { ContentUnderstandingClient } from "@azure/ai-content-understanding";
import { DefaultAzureCredential } from "@azure/identity";

const client = new ContentUnderstandingClient("<endpoint>", new DefaultAzureCredential());

Für Browserumgebungen verwenden Sie zur Authentifizierung das InteractiveBrowserCredential aus dem @azure/identity-Paket.

import { InteractiveBrowserCredential } from "@azure/identity";
import { ContentUnderstandingClient } from "@azure/ai-content-understanding";

const credential = new InteractiveBrowserCredential({
  tenantId: "<YOUR_TENANT_ID>",
  clientId: "<YOUR_CLIENT_ID>",
});
const client = new ContentUnderstandingClient("<endpoint>", credential);

Verwendung von API-Schlüssel

Sie können sich auch mit einem API-Schlüssel aus Ihrer Microsoft Foundry-Ressource authentifizieren:

import { ContentUnderstandingClient } from "@azure/ai-content-understanding";
import { AzureKeyCredential } from "@azure/core-auth";

const endpoint = process.env["CONTENTUNDERSTANDING_ENDPOINT"]!;
const apiKey = process.env["CONTENTUNDERSTANDING_KEY"]!;
const client = new ContentUnderstandingClient(endpoint, new AzureKeyCredential(apiKey));

Um Ihren API-Schlüssel zu erhalten:

  1. Geh zu Azure Portal
  2. Navigiere zu deiner Microsoft Foundry-Ressource
  3. Gehen Sie zu Resource Management>Schlüssel und Endpunkt
  4. Kopiere einen der Schlüssel (Schlüssel1 oder Schlüssel2)

Weitere Informationen zur Authentifizierung finden Sie unter Azure Identity Client Library.

JavaScript-Bündel

Um diese Clientbibliothek im Browser zu verwenden, müssen Sie zuerst einen Bundler verwenden. Für Details dazu, wie to do wird, siehe bitte unsere bündelnde Dokumentation.

Wichtige Konzepte

Vorgefertigte Analysegeräte

Content Understanding bietet eine umfangreiche Auswahl an vorgefertigten Analysatoren, die ohne jegliche Konfiguration einsatzbereit sind. Diese Analysatoren basieren auf Wissensdatenbanken mit Tausenden von realen Dokumentenbeispielen, die es ihnen ermöglichen, Dokumentstrukturen zu verstehen und sich an Format- und Inhaltsunterschiede anzupassen.

Vorgefertigte Analysatoren sind in mehrere Kategorien unterteilt:

  • RAG-Analysatoren – Optimiert für Szenarien der abrufaugmentierten Generierung mit semantischer Analyse und Markdown-Extraktion. Diese Analysatoren liefern für jedes Content-Element einen Markdown und einen Absatz Summary zurück:
    • prebuilt-documentSearch - Extrahiert Inhalte aus Dokumenten (PDF, Bilder, Office-Dokumente) mit Layout-Erhaltung, Tabellenerkennung, Figurenanalyse und strukturierter Markdown-Ausgabe. Optimiert für RAG-Szenarien.
    • prebuilt-imageSearch - Analysiert eigenständige Bilder und liefert eine ein-Absatz-Beschreibung des Bildinhalts. Optimiert für Bildverständnis und Suchszenarien. Für Bilder, die Text enthalten (einschließlich handschriftlichem Text), verwenden prebuilt-documentSearchSie .
    • prebuilt-audioSearch - Transkribiert Audioinhalte mit Sprechertagebuch, Zeitinformationen und Gesprächszusammenfassungen. Unterstützt mehrsprachige Transkription.
    • prebuilt-videoSearch - Analysiert Videoinhalte mit visueller Frame-Extraktion, Audiotranskription und strukturierten Zusammenfassungen. Bietet zeitliche Ausrichtung von visuellen und akustischen Inhalten und kann mehrere Segmente pro Video zurückgeben.
  • Inhaltsextraktionsanalysatoren – Fokus auf OCR und Layoutanalyse (z. B. prebuilt-read, ) prebuilt-layout
  • Basisanalysatoren – Grundlegende Inhaltsverarbeitungsfunktionen, die als Elternanalysatoren für kundenspezifische Analysatoren verwendet werden (z. B. prebuilt-document, prebuilt-image, , prebuilt-audio) prebuilt-video
  • Domänenspezifische Analysatoren – Vorkonfigurierte Analysatoren für gängige Dokumentenkategorien wie Finanzdokumente (Rechnungen, Quittungen, Kontoauszüge), Identitätsdokumente (Pässe, Führerscheine), Steuerformulare, Hypothekendokumente und Verträge sowie Versorgungsleistungen (Rechnungsauszüge)
  • Utility-Analysatoren – Spezialisierte Werkzeuge zur Schemagenerierung und Feldextraktion (z. B. prebuilt-documentFieldSchema, ) prebuilt-documentFields

Eine vollständige Liste der verfügbaren vorgefertigten Analysatoren und deren Fähigkeiten finden Sie in der Dokumentation Vorgefertigte Analysatoren.

Individuelle Analysatoren

Du kannst benutzerdefinierte Analysatoren mit spezifischen Feldschemata für multimodale Inhaltsverarbeitung (Dokumente, Bilder, Audio, Video) erstellen. Individuelle Analysatoren ermöglichen es Ihnen, domänenspezifische Informationen zu extrahieren, die auf Ihren Anwendungsfall zugeschnitten sind.

Inhaltstypen

Die API liefert basierend auf den Eingaben unterschiedliche Inhaltstypen zurück:

  • document - Für Dokumentdateien (PDF, HTML, Bilder, Office-Dokumente wie Word, Excel, PowerPoint und mehr). Bietet grundlegende Informationen wie Seitenanzahl und MIME-Typ. Rufen Sie detaillierte Informationen ab, darunter Seiten, Tabellen, Abbildungen, Absätze und vieles mehr.
  • audioVisual - Für Audio- und Videodateien. Bietet grundlegende Informationen wie Zeitangaben (Start-/Endzeiten) und Bildausschnitte (für Video). Beziehen Sie detaillierte Informationen ab, einschließlich Transkriptphrasen, Zeitangaben sowie für Video, Keyframe-Referenzen und mehr.

Asynchrone Vorgänge

Content Understanding-Operationen sind asynchrone, langlaufende Operationen. Der Workflow lautet:

  1. Analyse beginnen – Starten Sie die Analyseoperation (gibt sofort einen Operationsstandort zurück)
  2. Umfrage nach Ergebnissen – Untersuchen Sie den Operationsort, bis die Analyse abgeschlossen ist
  3. Prozessergebnisse – Extraktion und Darstellung der strukturierten Ergebnisse

Das SDK stellt Poller-Typen bereit, die das Polling automatisch handhaben, wenn verwendet pollUntilDone()wird. Für Analyseoperationen liefert das SDK einen Poller, der access zur Operations-ID liefert. Diese Operations-ID kann mit getResultFile und deleteResult Methoden verwendet werden.

Hauptklassen

  • ContentUnderstandingClient - Der Hauptclient zur Analyse von Inhalten sowie zur Erstellung, Verwaltung und Konfiguration von Analysatoren
  • AnalysisResult - Enthält die strukturierten Ergebnisse einer Analyseoperation, einschließlich Inhaltselementen, Markdown und Metadaten

Threadsicherheit

Wir garantieren, dass alle Client-Instanz-Methoden threadsicher und unabhängig voneinander sind. Dadurch wird sichergestellt, dass die Empfehlung, Clientinstanzen wiederzuverwenden, immer sicher ist, auch über Threads hinweg.

Weitere Konzepte

Client-Optionen | Zugriff auf die Antwort | Langlaufende Operationen | Umgang mit Fehlern | Diagnostics | Client-Lebenszeit

Beispiele

Du kannst dich mit verschiedenen APIs Samples vertraut machen.

Die Proben zeigen:

  • Konfiguration – Modellbereitstellungsstandardeinstellungen für vorgefertigte Analysatoren und benutzerdefinierte Analysatoren konfigurieren
  • Dokumenteninhaltsextraktion – Extrahieren Sie strukturierte Markdown-Inhalte aus PDFs und Bildern mit prebuilt-documentSearch, optimiert für RAG (Retrieval-Augmented Generation)-Anwendungen
  • Multimodale Inhaltsanalyse – Inhalte aus URLs über alle Modalitäten hinweg analysieren: Markdown und Zusammenfassungen aus Dokumenten, Bildern, Audio und Video prebuilt-documentSearchmit , prebuilt-imageSearch, , prebuilt-audioSearchund prebuilt-videoSearch
  • Domain-Specific Analyse – Extrahiere strukturierte Felder aus Rechnungen mit prebuilt-invoice
  • Erweiterte Dokumentfunktionen – Diagramme, Hyperlinks, Formeln und Anmerkungen aus Dokumenten extrahieren
  • Benutzerdefinierte Analysatoren – Erstellen Sie benutzerdefinierte Analysatoren mit Feldschemata für spezialisierte Extraktionsbedürfnisse
  • Dokumentklassifikation – Erstellen und verwenden Sie Klassifikatoren, um Dokumente zu kategorisieren
  • Analyzer-Management – Analyzer holen, listen, aktualisieren, kopieren und löschen
  • Ergebnisverwaltung – Ergebnisdateien aus der Videoanalyse abrufen und Analyseergebnisse löschen

Extrahieren Sie Markdown-Inhalte aus Dokumenten

Verwenden Sie den Analysator prebuilt-documentSearch , um Markdown-Inhalte aus Dokumenten zu extrahieren:

import { ContentUnderstandingClient } from "@azure/ai-content-understanding";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = process.env["CONTENTUNDERSTANDING_ENDPOINT"]!;
const client = new ContentUnderstandingClient(endpoint, new DefaultAzureCredential());

const documentUrl = "https://example.com/sample_invoice.pdf";

// Analyze document using prebuilt-documentSearch
const poller = client.analyze("prebuilt-documentSearch", [{ url: documentUrl }]);
const result = await poller.pollUntilDone();

// Extract markdown content
if (result.contents && result.contents.length > 0) {
  const content = result.contents[0];
  console.log("Markdown Content:");
  console.log(content.markdown);

  // Access document-specific properties
  if (content.kind === "document") {
    console.log(`Pages: ${content.startPageNumber} - ${content.endPageNumber}`);
  }
}

Extrahiere strukturierte Felder aus Rechnungen

Verwenden Sie den Analysator prebuilt-invoice , um strukturierte Rechnungsfelder zu extrahieren:

import {
  ContentUnderstandingClient,
  type DocumentContent,
  type ContentFieldUnion,
} from "@azure/ai-content-understanding";
import { DefaultAzureCredential } from "@azure/identity";

const endpoint = process.env["CONTENTUNDERSTANDING_ENDPOINT"]!;
const client = new ContentUnderstandingClient(endpoint, new DefaultAzureCredential());

const invoiceUrl = "https://example.com/invoice.pdf";

// Analyze invoice using prebuilt-invoice analyzer
const poller = client.analyze("prebuilt-invoice", [{ url: invoiceUrl }]);
const result = await poller.pollUntilDone();

if (result.contents && result.contents.length > 0) {
  const content = result.contents[0] as DocumentContent;

  // Helper function to extract field values
  const getFieldValue = (field: ContentFieldUnion | undefined): string | undefined => {
    if (!field) return undefined;
    if ("valueString" in field) return field.valueString;
    if ("valueDate" in field) return field.valueDate;
    if ("valueNumber" in field) return String(field.valueNumber);
    return undefined;
  };

  // Extract invoice fields
  const customerName = getFieldValue(content.fields?.["CustomerName"]);
  const invoiceTotal = getFieldValue(content.fields?.["InvoiceTotal"]);
  const invoiceDate = getFieldValue(content.fields?.["InvoiceDate"]);

  console.log(`Customer Name: ${customerName ?? "(None)"}`);
  console.log(`Invoice Total: ${invoiceTotal ?? "(None)"}`);
  console.log(`Invoice Date: ${invoiceDate ?? "(None)"}`);
}

Siehe das Verzeichnis samples für vollständige Beispiele.

Problembehandlung

Häufig auftretende Probleme

Fehler: "Access wegen ungültigem Abonnementschlüssel oder falschem API-Endpunkt abgelehnt"

  • Überprüfen Sie, ob Ihre Endpunkt-URL korrekt ist und den nachfolgenden Schrägstrich enthält
  • Stellen Sie sicher, dass Ihr API-Schlüssel gültig ist oder dass Ihre Microsoft Entra ID-Zugangsdaten die richtigen Berechtigungen haben
  • Stelle sicher, dass dir die Rolle Cognitive Services User in deinem Konto zugewiesen ist

Fehler: "Modellbereitstellung nicht gefunden" oder "Standardmodellbereitstellung nicht konfiguriert"

  • Stellen Sie sicher, dass Sie die erforderlichen Modelle (gpt-4.1, gpt-4.1-mini, text-embedding-3-large) in Microsoft Foundry bereitgestellt haben
  • Überprüfen Sie, dass Sie die Standardmodell-Deployments konfiguriert haben (siehe Configure Model Deployments)
  • Überprüfen Sie, ob Ihre Deployment-Namen mit dem übereinstimmen, was Sie in den Standardeinstellungen konfiguriert haben

Fehler: "Operation fehlgeschlagen" oder Timeout

  • Content Understanding-Operationen sind asynchron und können Zeit in Anspruch nehmen
  • Stellen Sie sicher, dass Sie die Ergebnisse korrekt mit pollUntilDone() dem Poller-Objekt abfragen
  • Überprüfen Sie den Betriebsstatus für weitere Details zum Ausfall

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann das Logging zur Laufzeit aktiviert werden, indem setLogLevel im @azure/logger aufgerufen wird:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Für detailliertere Anleitungen, wie man Logs aktiviert, findest du die @azure/logger-Paketdokumentation.

Testen

Dieses SDK enthält umfassende Tests, die in verschiedenen Modi ausgeführt werden können.

Schnellstart

# Install dependencies
pnpm install

# Build the SDK
npx turbo build --filter=@azure/ai-content-understanding...

# Run tests in playback mode (no Azure resources needed)
pnpm test

Testmodi

  • Wiedergabemodus (Standard): Verwendet voraufgezeichnete HTTP-Interaktionen, keine Azure Ressourcen benötigt
  • Record Mode: Läuft gegen Live-Azure-Dienste und zeichnet Interaktionen für zukünftige Wiedergaben auf
  • Live Mode: Läuft gegen Live-Azure-Dienste ohne Aufzeichnung

Einrichtung der Umgebung für Live-/Record-Tests

  1. Kopieren test/sample.env zu test/.env:

    cp test/sample.env test/.env

  2. Bearbeite test/.env und fülle deine tatsächlichen Werte aus:

    • CONTENTUNDERSTANDING_ENDPOINT: Ihr Microsoft Foundry-Ressourcenendpunkt
    • CONTENTUNDERSTANDING_KEY: Ihr API-Schlüssel (optional, wenn Sie DefaultAzureCredential verwenden)
    • Modell-Bereitstellungsnamen (erforderlich für vorgefertigte Analysatoren)

Tests im Record-Modus durchführen

Um neue Testinteraktionen aufzuzeichnen oder bestehende zu aktualisieren:

# Run tests in record mode
TEST_MODE=record pnpm test

Tests im Wiedergabemodus durchführen

Tests ohne Azure-Ressourcen durchführen (unter Verwendung vorab aufgezeichneter Interaktionen):

# Simply run tests (playback is the default mode)
pnpm test

# Or explicitly set playback mode
TEST_MODE=playback pnpm test

Paketbezogene / schnellere Arbeitsabläufe

  • Erstelle nur dieses Paket und seine Abhängigkeiten:

    npx turbo build --filter=@azure/ai-content-understanding... --token 1

  • Führe nur Node-Tests für schnellere Iteration durch (überspringe Browsertests):

    TEST_MODE=record pnpm test:node   # or TEST_MODE=playback pnpm test:node

Umgebungsvariablen

Sie können Zugangsdaten auf verschiedene Arten festlegen:

  1. Bevorzugt: Erstellentest/.env Sie, indem Sie Ihre Werte kopieren und ausfüllen test/sample.env

  2. Fallback: Platziere a .env an der Paketwurzel (im gleichen Verzeichnis wie package.json)

  3. Shell-Export: Exportiere Zugangsdaten direkt in deiner Shell:

    export CONTENTUNDERSTANDING_ENDPOINT="https://<your-resource>.services.ai.azure.com/"
export CONTENTUNDERSTANDING_KEY="<your_key_here>"
TEST_MODE=record pnpm test:node

Debug-Tipps

Wenn Sie Tests im Aufzeichnungsmodus ausführen, achten Sie auf Debug-Zeilen, die vom Test-Setup ausgedruckt werden:

DEBUG ENV ENDPOINT DEFINED: true
DEBUG ENV KEY DEFINED: true

Wichtig: Verbinde KEINE echten Schlüssel. Behalten Sie test/sample.env die Vorlage und stellen Sie sicher, dass test/.env sie in Ihrer .gitignoreSituation ist.

Fehlerbehebungstests

  • "Der Schlüssel muss ein nicht-leerer String sein": Der Testprozess konnte Ihr CONTENTUNDERSTANDING_KEYnicht finden. Stelle sicher, dass test/.env der Package-Root .env vorhanden ist und den Schlüssel enthält (oder exportiere ihn in deiner Shell), bevor du Tests ausführst.
  • "Ungültige Anfrage" LRO-Fehler: Stellen Sie sicher, dass Ihr Dienst/Ihre Region den von den Tests verwendeten Analyzer unterstützt und dass Netzwerk-access für URL-basierte Eingaben verfügbar ist.

Lokale Proben ausführen

Die Sample-Verzeichnisse sind aus dem pnpm-Arbeitsbereich ausgeschlossen, um Abhängigkeitskonflikte zu vermeiden. Um Samples mit der lokalen Entwicklungsversion des Pakets auszuführen:

Hinweis: Wenn man die Samples-Ordner ausführt pnpm link , pnpm install werden lokale Dateien wie package.json und pnpm-lock.yaml unter den Samples-Verzeichnissen aktualisiert. Diese Änderungen gelten nur für lokale Tests und sollten nicht überprüft werden. Wenn du sie versehentlich modifizierst, benutze git restore <path> sie zum Zurücksetzen.

  1. Bauen Sie das Paket zusammen:

    npx turbo build --filter=@azure/ai-content-understanding...

  2. Verlinken Sie das lokale Paket in den Beispielverzeichnissen:

    cd sdk/contentunderstanding/ai-content-understanding/samples/v1/typescript
pnpm link ../../../
cd ../javascript
pnpm link ../../../

  3. Installiere Abhängigkeiten in den Beispielverzeichnissen:

    cd sdk/contentunderstanding/ai-content-understanding/samples/v1/typescript
pnpm install
cd ../javascript
pnpm install

Alternative (keine package.json/lockfile-Änderungen)

Wenn Sie das lokale Paket verwenden möchten, ohne das Sample package.json zu verändern oder pnpm-lock.yaml, installieren Sie von einem verpackten Tarball, ohne zu speichern:

  1. Bauen Sie das Paket zusammen:

    npx turbo build --filter=@azure/ai-content-understanding...

  2. Erstellen Sie einen lokalen Tarball:

    cd sdk/contentunderstanding/ai-content-understanding
pnpm pack --pack-destination /tmp

  3. Installiere die Tarball in den Samples (kein Speicher, keine Sperrdatei):

    cd sdk/contentunderstanding/ai-content-understanding/samples/v1/typescript
npm install --no-save --no-package-lock /tmp/azure-ai-content-understanding-*.tgz
cd ../javascript
npm install --no-save --no-package-lock /tmp/azure-ai-content-understanding-*.tgz

Ausführen einer Probe

Nach der Installation von Abhängigkeiten kann man einzelne Samples ausführen.

Einrichtung von Umweltvariablen:

Kopiere die sample.env Datei, um eine .env Datei im Root-Sample-Verzeichnis zu erstellen. Führe folgende Befehle aus dem Paketroot aus (sdk/contentunderstanding/ai-content-understanding):

# For TypeScript samples
cp sample.env samples/v1/typescript/.env

# For JavaScript samples
cp sample.env samples/v1/javascript/.env

Dann bearbeiten Sie die .env Datei und füllen Sie Ihre tatsächlichen Werte ein:

CONTENTUNDERSTANDING_ENDPOINT=https://<your-resource>.services.ai.azure.com/
CONTENTUNDERSTANDING_KEY=<your-api-key>

Hinweis: Die .env Datei sollte sich im Root-Bereich des Beispielordners befinden (gleiche Ebene wie package.json), nicht im Inneren src/ oder dist/.

TypeScript-Beispiele:

cd samples/v1/typescript
npm run build
node dist/analyzeBinary.js

JavaScript-Beispiele:

cd samples/v1/javascript
node analyzeBinary.js

Für vollständige Einrichtungsanweisungen und verfügbare Beispiele siehe:

Nächste Schritte

Contributing

Wenn Sie zu dieser Bibliothek beitragen möchten, lesen Sie bitte den beitragenden Leitfaden, um mehr darüber zu erfahren, wie man den Code erstellt und testet.

  • Last updated on