Udostępnij za pośrednictwem

Indeksowanie obiektów blob i plików oznaczonych językiem Markdown w usłudze Azure AI Search

Uwaga

Ta funkcja jest obecnie w publicznej wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie jest zalecana w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą być nieobsługiwane lub ograniczone. Aby uzyskać więcej informacji, zobacz Uzupełniające warunki korzystania z wersji zapoznawczych platformy Microsoft Azure.

W usłudze Azure AI Search indeksatory dla usług Azure Blob Storage, Azure Files i OneLake obsługują tryb analizowania plików Markdown w trybie markdown. Pliki markdown można indeksować na dwa sposoby:

  • Tryb analizowania jeden do wielu, tworząc wiele dokumentów wyszukiwania dla każdego pliku Markdown
  • Tryb analizowania jeden do jednego, tworząc jeden dokument wyszukiwania dla pliku Markdown

Napiwek

Przejdź do Samouczka: wyszukiwanie danych Markdown z Azure Blob Storage po zapoznaniu się z tym artykułem.

Wymagania wstępne

  • Obsługiwane źródło danych: Azure Blob Storage, Azure File Storage, OneLake w usłudze Microsoft Fabric.

    W przypadku usługi OneLake upewnij się, że spełniasz wszystkie wymagania indeksatora OneLake.

    Usługa Azure Storage dla indeksatorów obiektów blob i indeksatorów plików to wystąpienie o standardowej wydajności (ogólnego przeznaczenia v2), które obsługuje warstwy dostępu gorąca i chłodna.

Parametry trybu analizowania języka Markdown

Parametry trybu analizowania są określane w definicji indeksatora podczas tworzenia lub aktualizowania indeksatora.

POST https://[service name].search.windows.net/indexers?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

{
  "name": "my-markdown-indexer",
  "dataSourceName": "my-blob-datasource",
  "targetIndexName": "my-target-index",
  "parameters": {
    "configuration": {
      "parsingMode": "markdown",
      "markdownParsingSubmode": "oneToMany",
      "markdownHeaderDepth": "h6"
    }
  },
}

Indeksator obiektów blob udostępnia parametr submode do określenia struktury danych wyjściowych dokumentów wyszukiwania. Tryb parsowania Markdown udostępnia następujące opcje podtrybu:

tryb parsowania tryb podrzędny Wyszukaj dokument opis
markdown oneToMany Wiele na każdy blob (ustawienie domyślne) Dzieli język Markdown na wiele dokumentów wyszukiwania, z których każdy przedstawia sekcję zawartości (inną niż nagłówek) pliku Markdown. Można pominąć tryb podrzędny, chyba że chcesz przeanalizować jeden do jednego.
markdown oneToOne Jeden na klaster danych Analizuje język Markdown w jednym dokumencie wyszukiwania, a sekcje są mapowane na określone nagłówki w pliku Markdown.

W przypadku oneToMany podmodu należy przejrzeć temat Indeksowanie jednego obiektu blob w celu utworzenia wielu dokumentów wyszukiwania, aby zrozumieć, jak indeksator blob obsługuje uściślanie klucza dokumentu dla wielu dokumentów wyszukiwania utworzonych z tego samego obiektu blob.

W kolejnych sekcjach bardziej szczegółowo opisano poszczególne podmody. Jeśli nie znasz klientów i pojęć indeksatora, zobacz Tworzenie indeksatora wyszukiwania. Należy również zapoznać się ze szczegółami podstawowej konfiguracji indeksatora obiektów blob, która nie jest powtarzana w tym miejscu.

Opcjonalne parametry analizowania języka Markdown

W parametrach jest rozróżniana wielkość liter.

Nazwa parametru Dozwolone wartości opis
markdownHeaderDepth h1, , h2, h3, h4, , h5h6(default) Ten parametr określa najgłębszy poziom nagłówka, który jest brany pod uwagę podczas analizowania, co pozwala na elastyczną obsługę struktury dokumentu (na przykład gdy markdownHeaderDepth jest ustawiona na h1, analizator rozpoznaje tylko nagłówki najwyższego poziomu, które zaczynają się od "#", a wszystkie nagłówki niższego poziomu są traktowane jako zwykły tekst). Jeśli nie zostanie określony, wartość domyślna to h6.

To ustawienie można zmienić po początkowym utworzeniu indeksatora, jednak struktura wynikowych dokumentów wyszukiwania może ulec zmianie w zależności od zawartości języka Markdown.

Obsługiwane elementy języka Markdown

Analizowanie języka Markdown spowoduje podzielenie zawartości tylko na podstawie nagłówków. Wszystkie inne elementy, takie jak listy, bloki kodu, tabele itd., są traktowane jako zwykły tekst i przekazywane do pola zawartości.

Przykładowa zawartość języka Markdown

Następująca zawartość języka Markdown jest używana dla przykładów na tej stronie:

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Użyj trybu analizowania jeden do wielu

Tryb analizowania od jednego do wielu dzieli pliki Markdown na wiele dokumentów wyszukiwania, gdzie każdy dokument odpowiada konkretnej sekcji zawartości pliku Markdown na podstawie metadanych nagłówka w odpowiadającym miejscu dokumentu. Markdown jest przetwarzany na podstawie nagłówków na dokumenty wyszukiwania, które zawierają następujące treści:

  • content: ciąg zawierający nieprzetworzone znaczniki Markdown znalezione w określonej lokalizacji na podstawie metadanych nagłówka w tym momencie dokumentu.

  • sections: obiekt zawierający podpola metadanych nagłówka aż do żądanego poziomu nagłówka. Na przykład, gdy markdownHeaderDepth jest ustawiony na h3, zawiera pola tekstowe h1, h2 i h3. Te pola są indeksowane poprzez odzwierciedlenie tej struktury w indeksie lub poprzez mapowania pól w formacie /sections/h1, sections/h2, itd. Zobacz konfiguracje indeksu i indeksatora w poniższych przykładach, aby uzyskać przykłady w kontekście. Zawarte pola podrzędne to:

    • h1 - Ciąg zawierający wartość nagłówka h1. Pusty ciąg, jeśli nie zostanie ustawiony w tym momencie w dokumencie.
    • (Opcjonalnie) h2- Ciąg zawierający wartość nagłówka h2. Pusty ciąg, jeśli nie zostanie ustawiony w tym momencie w dokumencie.
    • (Opcjonalnie) h3- Ciąg zawierający wartość nagłówka h3. Pusty ciąg, jeśli nie zostanie ustawiony w tym momencie w dokumencie.
    • (Opcjonalnie) h4- Ciąg zawierający wartość nagłówka h4. Pusty ciąg, jeśli nie zostanie ustawiony w tym momencie w dokumencie.
    • (Opcjonalnie) h5- Ciąg zawierający wartość nagłówka h5. Pusty ciąg, jeśli nie zostanie ustawiony w tym momencie w dokumencie.
    • (Opcjonalnie) h6- Ciąg zawierający wartość nagłówka h6. Pusty ciąg, jeśli nie zostanie ustawiony w tym momencie w dokumencie.

  • ordinal_position: wartość całkowita wskazująca położenie sekcji w hierarchii dokumentów. To pole służy do porządkowania sekcji w ich oryginalnej sekwencji, jak są one wyświetlane w dokumencie, zaczynając od pozycji 1 i zwiększając sekwencyjnie dla każdego nagłówka.

Schemat indeksu dla analizowania jeden do wielu

Przykładowa konfiguracja indeksu może wyglądać mniej więcej tak:

{
  "name": "my-markdown-index",
  "fields": [
  {
    "name": "id",
    "type": "Edm.String",
    "key": true
  },
  {
    "name": "content",
    "type": "Edm.String",
  },
  {
    "name": "ordinal_position",
    "type": "Edm.Int32"
  },
  {
    "name": "sections",
    "type": "Edm.ComplexType",
    "fields": [
    {
      "name": "h1",
      "type": "Edm.String"
    },
    {
      "name": "h2",
      "type": "Edm.String"
    }]
  }]
}

Definicja indeksatora do analizowania "jeden do wielu"

Jeśli nazwy pól i typy danych są zgodne, indeksator obiektów blob może wywnioskować mapowanie bez jawnego mapowania pól obecnego w żądaniu, więc konfiguracja indeksatora zgodna z podaną konfiguracją indeksu może wyglądać następująco:

POST https://[service name].search.windows.net/indexers?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

{
  "name": "my-markdown-indexer",
  "dataSourceName": "my-blob-datasource",
  "targetIndexName": "my-target-index",
  "parameters": {
    "configuration": { "parsingMode": "markdown" }
  },
}

Uwaga

submode nie trzeba tutaj ustawiać jawnie, ponieważ oneToMany jest ustawieniem domyślnym.

Dane wyjściowe indeksatora do analizy jeden-do-wielu

Ten plik Markdown spowoduje wyświetlenie trzech dokumentów wyszukiwania po indeksowaniu ze względu na trzy sekcje zawartości. Dokument wyszukiwania wynikający z pierwszej sekcji zawartości dostarczonego dokumentu Markdown zawiera następujące wartości dla content, sections, h1 i h2.

{
  {
    "content": "Content for section 1.\r\n",
    "sections": {
      "h1": "Section 1",
      "h2": ""
    },
    "ordinal_position": 1
  },
  {
    "content": "Content for subsection 1.1.\r\n",
    "sections": {
      "h1": "Section 1",
      "h2": "Subsection 1.1"
    },
    "ordinal_position": 2
  },
  {
    "content": "Content for section 2.\r\n",
    "sections": {
      "h1": "Section 2",
      "h2": ""
    },
    "ordinal_position": 3
  }
}

Mapowanie pól typu jeden-do-wielu w indeksie wyszukiwania

Mapowania pól kojarzą pole źródłowe z polem docelowym w sytuacjach, w których nazwy pól i typy nie są identyczne. Jednak mapowania pól mogą być również używane do dopasowywania części dokumentu Markdown i przenoszenia ich do najwyższego poziomu pól w dokumencie wyszukiwania.

Poniższy przykład ilustruje ten scenariusz. Aby uzyskać więcej informacji na temat mapowań pól w ogóle, zobacz Mapowania pól.

Przyjmij indeks wyszukiwania z następującymi polami: raw_content typu Edm.String, h1_header typu Edm.String, oraz h2_header typu Edm.String. Aby zamapować znacznik Markdown na żądany kształt, użyj następujących mapowań pól:

"fieldMappings" : [
    { "sourceFieldName" : "/content", "targetFieldName" : "raw_content" },
    { "sourceFieldName" : "/sections/h1", "targetFieldName" : "h1_header" },
    { "sourceFieldName" : "/sections/h2", "targetFieldName" : "h2_header" },
  ]

Wynikowy dokument wyszukiwania w indeksie wygląda następująco:

{
  {
    "raw_content": "Content for section 1.\r\n",
    "h1_header": "Section 1",
    "h2_header": "",
  },
  {
    "raw_content": "Content for section 1.1.\r\n",
    "h1_header": "Section 1",
    "h2_header": "Subsection 1.1",
  },
  {
    "raw_content": "Content for section 2.\r\n",
    "h1_header": "Section 2",
    "h2_header": "",
  }
}

Korzystanie z trybu analizowania jeden do jednego

W trybie analizowania jeden do jednego cały dokument Markdown jest indeksowany jako pojedynczy dokument wyszukiwania, zachowując hierarchię i strukturę oryginalnej zawartości. Ten tryb jest najbardziej przydatny, gdy pliki do indeksowania mają wspólną strukturę, dzięki czemu można użyć tej wspólnej struktury w indeksie, aby umożliwić wyszukiwanie odpowiednich pól.

W definicji indeksatora ustaw parsingMode na "markdown" i użyj opcjonalnego parametru markdownHeaderDepth, aby zdefiniować maksymalną głębokość nagłówka dla podziału na fragmenty. Jeśli nie zostanie określony, domyślnie ustawia się na h6, obejmując wszystkie możliwe głębokości nagłówka.

Markdown jest przetwarzany na podstawie nagłówków na dokumenty wyszukiwania, które zawierają następujące treści:

  • document_content: zawiera pełny tekst języka Markdown jako pojedynczy ciąg. To pole służy jako nieprzetworzona reprezentacja dokumentu wejściowego.

  • sections: tablica obiektów, która zawiera hierarchiczną reprezentację sekcji w dokumencie Markdown. Każda sekcja jest reprezentowana jako obiekt w tej tablicy i odwzorowuje strukturę dokumentu w sposób hierarchiczny, odpowiadający nagłówkom i ich odpowiedniej zawartości. Pola są dostępne za pośrednictwem mapowań pól, odwołując się do ścieżki, na przykład /sections/content. Obiekty w tej tablicy mają następujące właściwości:

    • header_level: ciąg wskazujący poziom nagłówka (h1, h2, h3itp.) w składni języka Markdown. To pole ułatwia zrozumienie hierarchii i struktury zawartości.

    • header_name: ciąg zawierający tekst nagłówka, który pojawia się w dokumencie Markdown. To pole zawiera etykietę lub tytuł sekcji.

    • content: ciąg zawierający zawartość tekstową, która bezpośrednio następuje po nagłówku, aż do następnego nagłówka. To pole przechwytuje szczegółowe informacje lub opis skojarzony z nagłówkiem. Jeśli nie ma zawartości bezpośrednio pod nagłówkiem, jest to pusty ciąg.

    • ordinal_position: wartość całkowita wskazująca położenie sekcji w hierarchii dokumentów. To pole służy do porządkowania sekcji w oryginalnej sekwencji, gdy pojawiają się w dokumencie, począwszy od porządkowej pozycji 1 i zwiększając ją sekwencyjnie dla każdego bloku zawartości.

    • sections: Tablica zawierająca obiekty reprezentujące podsekcje zagnieżdżone w bieżącej sekcji. Ta tablica ma tę samą strukturę co tablica na najwyższym poziomie sections, umożliwiając odwzorowanie wielu poziomów zagnieżdżonej zawartości. Każdy obiekt podsekcji zawiera również właściwości header_level, header_name, content i ordinal_position, umożliwiając strukturę rekursywną reprezentującą hierarchię zawartości języka Markdown.

Oto przykładowy kod Markdown, którego używamy do wyjaśnienia schematu indeksu zaprojektowanego wokół każdego trybu analizowania.

# Section 1
Content for section 1.

## Subsection 1.1
Content for subsection 1.1.

# Section 2
Content for section 2.

Schemat indeksu do analizowania w trybie jeden do jednego

Jeśli nie używasz mapowań pól, kształt indeksu powinien odzwierciedlać kształt zawartości języka Markdown. Biorąc pod uwagę strukturę przykładowego języka Markdown z dwiema sekcjami i pojedynczą podsekcją, indeks powinien wyglądać podobnie do poniższego przykładu:

{
  "name": "my-markdown-index",
  "fields": [
  {
    "name": "document_content",
    "type": "Edm.String",
  {
    "name": "sections",
    "type": "Edm.ComplexType",
    "fields": [
    {
      "name": "header_level",
      "type": "Edm.String",
    },
    {
      "name": "header_name",
      "type": "Edm.String",
    },
    {
      "name": "content",
      "type": "Edm.String"
    },
    {
      "name": "ordinal_position",
      "type": "Edm.Int"
    },
    {
      "name": "sections",
      "type": "Edm.ComplexType",
      "fields": [
      {
        "name": "header_level",
        "type": "Edm.String",
      },
      {
        "name": "header_name",
        "type": "Edm.String",
      },
      {
        "name": "content",
        "type": "Edm.String"
      },
      {
        "name": "ordinal_position",
        "type": "Edm.Int"
      }]
    }]
  }
}

Definicja indeksatora na potrzeby analizowania jeden do jednego

POST https://[service name].search.windows.net/indexers?api-version=2025-05-01-preview
Content-Type: application/json
api-key: [admin key]

{
  "name": "my-markdown-indexer",
  "dataSourceName": "my-blob-datasource",
  "targetIndexName": "my-target-index",
  "parameters": {
    "configuration": {
      "parsingMode": "markdown",
      "markdownParsingSubmode": "oneToOne",
    }
  }
}

Dane wyjściowe indeksatora do analizy jeden do jednego

Ponieważ Markdown, który chcemy indeksować, sięga tylko do głębokości h2 ("##"), potrzebujemy pól sections zagnieżdżonych do głębokości 2, aby to dopasować. Ta konfiguracja spowoduje wyświetlenie następujących danych w indeksie:

  "document_content": "# Section 1\r\nContent for section 1.\r\n## Subsection 1.1\r\nContent for subsection 1.1.\r\n# Section 2\r\nContent for section 2.\r\n",
  "sections": [
    {
      "header_level": "h1",
      "header_name": "Section 1",
      "content": "Content for section 1.",
      "ordinal_position": 1,
      "sections": [
        {
          "header_level": "h2",
          "header_name": "Subsection 1.1",
          "content": "Content for subsection 1.1.",
          "ordinal_position": 2,
        }]
    }],
    {
      "header_level": "h1",
      "header_name": "Section 2",
      "content": "Content for section 2.",
      "ordinal_position": 3,
      "sections": []
    }]
  }

Jak widać, pozycja porządkowa zwiększa się w zależności od lokalizacji zawartości w obrębie dokumentu.

Należy również zauważyć, że jeśli poziomy nagłówków są pomijane w zawartości, struktura wynikowego dokumentu odzwierciedla nagłówki obecne w zawartości języka Markdown, ale niekoniecznie zawiera zagnieżdżone sekcje kolejno od h1 do h6. Na przykład gdy dokument rozpoczyna się od h2, pierwszym elementem tablicy sekcji najwyższego poziomu jest h2.

Mapowanie pól jeden do jednego w indeksie wyszukiwania

Jeśli chcesz wyodrębnić pola z nazwami niestandardowymi z dokumentu, możesz użyć mapowań pól, aby to zrobić. Korzystając z tego samego przykładu języka Markdown, jak poprzednio, rozważ następującą konfigurację indeksu:

{
  "name": "my-markdown-index",
  "fields": [
    {
      "name": "document_content",
      "type": "Edm.String",
    },
    {
      "name": "document_title",
      "type": "Edm.String",
    },
    {
      "name": "opening_subsection_title"
      "type": "Edm.String",
    }
    {
      "name": "summary_content",
      "type": "Edm.String",
    }
  ]
}

Wyodrębnianie określonych pól z analizowanego kodu Markdown jest obsługiwane podobnie do sposobu, w jaki ścieżki dokumentów znajdują się w elementach outputFieldMappings, z wyjątkiem ścieżki zaczyna się od /sections zamiast /document. Na przykład /sections/0/content mapuje zawartość pod elementem na pozycję 0 w tablicy sekcji.

Przykład silnego przypadku użycia może wyglądać mniej więcej tak: wszystkie pliki Markdown mają tytuł dokumentu w pierwszym h1, tytuł podsekcji w pierwszej h2części i podsumowanie w treści końcowego akapitu poniżej końcowego h1. Do indeksowania tylko tej zawartości można użyć następujących mapowań pól:

"fieldMappings" : [
  { "sourceFieldName" : "/content", "targetFieldName" : "raw_content" },
  { "sourceFieldName" : "/sections/0/header_name", "targetFieldName" : "document_title" },
  { "sourceFieldName" : "/sections/0/sections/header_name", "targetFieldName" : "opening_subsection_title" },
  { "sourceFieldName" : "/sections/1/content", "targetFieldName" : "summary_content" },
]

W tym miejscu wyodrębnisz tylko odpowiednie elementy z tego dokumentu. Aby efektywnie korzystać z tej funkcji, dokumenty, które planujesz indeksować, powinny współużytkować tę samą hierarchiczną strukturę nagłówka.

Wynikowy dokument wyszukiwania w indeksie wygląda następująco:

{
  "content": "Content for section 1.\r\n",
  "document_title": "Section 1",
  "opening_subsection_title": "Subsection 1.1",
  "summary_content": "Content for section 2."
}

Uwaga

Te przykłady określają sposób używania tych trybów analizowania w całości z mapowaniami pól lub bez nich, ale można użyć obu tych metod w jednym scenariuszu, jeśli odpowiada to Twoim potrzebom.

Następne kroki