Indeksowanie obiektów blob i plików markdown w usłudze Azure AI Search

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

• Tryb analizowania jeden do wielu, tworząc wiele dokumentów wyszukiwania na plik Markdown
• Tryb analizowania jeden do jednego, tworząc jeden dokument wyszukiwania dla pliku Markdown

• 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 standardowe wystąpienie wydajności (ogólnego przeznaczenia w wersji 2), które obsługuje warstwy dostępu Gorąca i Chłodna.

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

POST https://[service name].search.windows.net/indexers?api-version=2024-11-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 submode parametr służący do określania danych wyjściowych struktury dokumentów wyszukiwania. Tryb analizowania języka Markdown udostępnia następujące opcje podmodu:

W przypadku oneToMany podmodu należy przejrzeć temat Indeksowanie jednego obiektu blob, aby utworzyć wiele dokumentów wyszukiwania, aby zrozumieć, jak indeksator obiektów 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.

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

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.

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.

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.

Tryb analizowania jeden do wielu analizuje pliki Markdown w wielu dokumentach wyszukiwania, gdzie każdy dokument odpowiada określonej sekcji zawartości pliku Markdown na podstawie metadanych nagłówka w tym momencie dokumentu. Język Markdown jest analizowany na podstawie nagłówków w dokumentach wyszukiwania, które zawierają następującą zawartość:

• 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 pola podrzędne metadanych nagłówka do żądanego poziomu nagłówka. Na przykład gdy markdownHeaderDepth jest ustawiona wartość h3, zawiera pola ciągów h1, h2i h3. Te pola są indeksowane przez dublowanie tej struktury w indeksie lub mapowania pól w formacie /sections/h1, sections/h2itp. Zobacz konfiguracje indeksu i indeksatora w poniższych przykładach, aby zapoznać się z przykładami 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, począwszy od porządkowej pozycji 1 i przyrostowego sekwencyjnie dla każdego nagłówka.

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"
    }]
  }]
}

Jeśli nazwy pól i typy danych są wyrównane, indeksator obiektów blob może wywnioskować mapowanie bez jawnego mapowania pól w żądaniu, więc konfiguracja indeksatora odpowiadająca podanej konfiguracji indeksu może wyglądać następująco:

POST https://[service name].search.windows.net/indexers?api-version=2024-11-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" }
  },
}

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 contentelementów , , sectionsh1i 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
  }
}   

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 "lift" do pól najwyższego poziomu dokumentu 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 i h2_header typu Edm.StringEdm.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": "",
  }
}

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 parsingMode ustaw parametr na "markdown" wartość i użyj opcjonalnego markdownHeaderDepth parametru, aby zdefiniować maksymalną głębokość nagłówka dla fragmentowania. Jeśli nie zostanie określony, wartość domyślna to h6, przechwytując wszystkie możliwe głębokości nagłówka.

Język Markdown jest analizowany na podstawie nagłówków w dokumentach wyszukiwania, które zawierają następującą zawartość:

• 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 przechwytuje strukturę dokumentu w sposób zagnieżdżony odpowiadający nagłówkom i 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ądkowego położenia 1 i przyrostowego sekwencyjnie dla każdego bloku zawartości.

  • sections: Tablica zawierająca obiekty reprezentujące podsekcje zagnieżdżone w bieżącej sekcji. Ta tablica jest zgodna z tą samą strukturą co tablica najwyższego poziomu sections , umożliwiająca reprezentację wielu poziomów zagnieżdżonej zawartości. Każdy obiekt podsekcji zawiera header_levelrównież właściwości , header_namecontent, iordinal_position, włączając strukturę rekursywną reprezentującą i 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.

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"
      }]
    }]
  }
}

POST https://[service name].search.windows.net/indexers?api-version=2024-11-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",
    }
  }
}

Ponieważ indeks języka Markdown, który chcemy indeksować, przechodzi tylko do głębokości h2 ("##"), potrzebujemy sections pól zagnieżdżonych do głębokości 2, aby je 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ć, położenie porządkowe zwiększa się na podstawie lokalizacji zawartości w dokumencie.

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

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."
}

• Konfigurowanie indeksatorów obiektów blob
• Definiowanie mapowań pól
• Indexers overview (Omówienie indeksatorów)
• Jak indeksować obiekty blob CSV za pomocą indeksatora obiektów blob
• Samouczek: wyszukiwanie danych markdown z usługi Azure Blob Storage