Indeksowanie obiektów blob i plików Markdown w Wyszukiwanie AI platformy Azure

W Wyszukiwanie AI platformy Azure indeksatory dla Azure Blob Storage, Azure Files i Microsoft OneLake obsługują tryb analizy markdown dla plików Markdown. Pliki markdown można indeksować na dwa sposoby:

• Tryb parsowania jeden-do-wielu, który tworzy wiele dokumentów wyszukiwania dla każdego pliku Markdown.
• Tryb analizowania jeden do jednego, który tworzy jeden dokument wyszukiwania na plik Markdown.

Wymagania wstępne

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

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

  Azure Storage dla indeksatorów obiektów blob i indeksatorów plików (wersja zapoznawcza) 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 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=2026-04-01
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 określający strukturę wyjściową dokumentów wyszukiwania. Tryb parsowania Markdown udostępnia następujące podtryby.

W przypadku oneToMany podmodu należy przejrzeć temat Indeksowanie jednego obiektu blob, aby utworzyć wiele dokumentów wyszukiwania, aby zrozumieć, w jaki sposób indeksator blobów obsługuje rozróżnianie 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

Parametry są wrażliwe na wielkość liter.

To ustawienie można zmienić po 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

Analiza Markdownu dzieli zawartość wyłącznie według nagłówków. Wszystkie inne elementy, takie jak listy, bloki kodu i tabele, 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 parsowania jeden do wielu

Tryb parsowania jeden do wielu przekształca pliki Markdown w wiele dokumentów wyszukiwania, gdzie każdy dokument odpowiada określonej sekcji zawartości pliku Markdown na podstawie metadanych nagłówków w danym 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 znaków, który zawiera surowy tekst Markdown, znaleziony 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 ustawiony na h3, zawiera pola ciągów h1, h2, i h3. Te pola są indeksowane przez dublowanie tej struktury w indeksie lub mapowania pól w formacie /sections/h1, /sections/h2itd. Zobacz konfiguracje indeksu i indeksatora w poniższych przykładach, aby zobaczyć, jak działają 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 pojawiają się w dokumencie, zaczynając od pozycji porządkowej 1 i zwiększając jego wartość sekwencyjnie dla każdego nagłówka.

Schemat indeksowania dla analizy relacji 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 blob może wywnioskować mapowanie bez konieczności podania jawnego mapowania pól w żądaniu, więc konfiguracja indeksatora odpowiadająca konfiguracji indeksu, która została podana, może wyglądać następująco:

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

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

Dane wyjściowe indeksatora do analizowania "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 elementów 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 podniesienia ich 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 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 dzielenia. Jeśli nie zostanie określony, wartość domyślna to h6, obejmują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 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, h3itd.) 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, wartość jest pustym ciągiem.

  • 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 kolejności, gdy pojawiają się w dokumencie, zaczynając od pozycji 1 i zwiększając o jeden 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 również właściwości header_level, header_name, content i ordinal_position, umożliwiając rekurencyjną strukturę reprezentującą hierarchię zawartości języka Markdown.

Oto przykładowy kod Markdown, którego używamy do wyjaśnienia schematów indeksów zaprojektowanych 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 na potrzeby analizowania 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": "id",
    "type": "Edm.String",
    "key": true
  },
  {
    "name": "document_content",
    "type": "Edm.String"
  },
  {
    "name": "sections",
    "type": "Collection(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.Int32"
    },
    {
      "name": "sections",
      "type": "Collection(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.Int32"
      }]
    }]
  }]
}

Definicja indeksatora na potrzeby analizowania jeden do jednego

POST https://[service name].search.windows.net/indexers?api-version=2026-04-01
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ż 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.

Jeśli poziomy nagłówka są pomijane w treści, struktura wynikowego dokumentu odzwierciedla nagłówki obecne w zawartości Markdown i nie musi zawierać kolejnych zagnieżdżonych sekcji 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

Aby wyodrębnić pola z nazwami niestandardowymi z dokumentu, możesz użyć mapowań pól. 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 do zawartości pod elementem znajdującym się na pozycji 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."
}

Zarządzanie przestarzałymi dokumentami z ponownego indeksowania w Markdown

W przypadku korzystania z trybu analizowania jeden do wielu ponowne indeksowanie zmodyfikowanego pliku Markdown może spowodować nieaktualne lub zduplikowane dokumenty, jeśli sekcje zostaną usunięte. To zachowanie jest specyficzne dla trybu jeden do wielu i nie dotyczy analizowania jeden do jednego.

Omówienie zachowania

Tryb analizowania jeden do wielu

W oneToMany trybie każda sekcja języka Markdown (oparta na nagłówkach) jest indeksowana jako oddzielny dokument wyszukiwania. Gdy plik zostanie ponownie zaindeksowany:

• Brak automatycznego usuwania: indeksator zastępuje istniejące dokumenty nowymi dokumentami, ale nie usuwa dokumentów, które nie odpowiadają już żadnej zawartości w zaktualizowanym pliku.
• Potencjalne duplikaty: ten problem pojawia się tylko wtedy, gdy więcej sekcji zostanie usuniętych niż wstawionych między przebiegami indeksowania. W takich przypadkach pozostałe dokumenty z poprzedniej wersji pozostają w indeksie, co prowadzi do nieaktualnych wpisów, które nie odzwierciedlają już bieżącego stanu pliku źródłowego.

Tryb analizowania jeden do jednego

W oneToOne trybie cały plik Markdown jest indeksowany jako pojedynczy dokument wyszukiwania. Gdy plik zostanie ponownie zaindeksowany:

• Zachowanie zastępowania: istniejący dokument jest całkowicie zastępowany nową wersją.
• Brak przestarzałych sekcji: gdy plik zostanie ponownie zaindeksowany, istniejący dokument zostanie zastąpiony zaktualizowaną wersją i usunięta zawartość nie zostanie już uwzględniona. Jedynym wyjątkiem jest zmiana ścieżki pliku lub identyfikatora URI obiektu blob, co może spowodować utworzenie nowego dokumentu obok starego.

Opcje obejścia

Aby upewnić się, że indeks odzwierciedla bieżący stan plików Markdown, rozważ jedno z następujących podejść:

Opcja 1. Usuwanie miękkie z metadanymi

: Ta metoda używa miękkiego usuwania do usuwania dokumentów skojarzonych z określonym blobem. Aby uzyskać więcej informacji, zobacz wykrywanie zmian i usuwanie przy użyciu indeksatorów dla Azure Storage w Wyszukiwanie AI platformy Azure.

Kroki:

1. Oznacz obiekt blob jako usunięty, ustawiając pole metadanych.
2. Niech indeksator zostanie uruchomiony. Usuwa wszystkie dokumenty w indeksie skojarzonym z tym obiektem blob.
3. Usuń znacznik usuwania nietrwałego i ponownie zaindeksuj plik.

Opcja 2. Użyj interfejsu API usuwania

Przed ponownym indeksowaniem zmodyfikowanego pliku Markdown jawnie usuń istniejące dokumenty skojarzone z tym plikiem przy użyciu interfejsu API usuwania. Możesz wykonać jedną z następujących czynności:

• Ręcznie zidentyfikuj poszczególne nieaktualne dokumenty, identyfikując duplikaty w indeksie przeznaczonym do usunięcia. Może to być możliwe w przypadku małych, dobrze zrozumiałych zmian, ale może być czasochłonne.
• (Zalecane) Przed ponownym indeksowaniem usuń wszystkie dokumenty wygenerowane z tego samego pliku nadrzędnego, aby uniknąć niespójności.

Kroki:

1. Zidentyfikuj identyfikator dokumentów skojarzonych z plikiem. Użyj zapytania, takiego jak w poniższym przykładzie, id aby pobrać identyfikatory kluczy dokumentu (na przykład lub chunk_id) dla wszystkich dokumentów powiązanych z określonym plikiem. Zastąp metadata_storage_path odpowiednie pole w indeksie, które mapuje na ścieżkę pliku lub URI obiektu blob. To pole musi być kluczem.

   GET https://[service name].search.windows.net/indexes/[index name]/docs?api-version=2026-04-01
   Content-Type: application/json
   api-key: [admin key]
   
   
     {
         "filter": "metadata_storage_path eq 'https://<storage-account>.blob.core.windows.net/<container-name>/<file-name>.md'",
         "select": "id"
     }
   

2. Wyślij żądanie usunięcia dla dokumentów z zidentyfikowanymi kluczami.

   POST https://[service name].search.windows.net/indexes/[index name]/docs/index?api-version=2026-04-01
   Content-Type: application/json
   api-key: [admin key]
   
   {
     "value": [
       {
         "@search.action": "delete",
         "id": "aHR0c...jI1"
       },
       {
         "@search.action": "delete",
         "id": "aHR0...MQ2"
       }
     ]
   }
   

3. Ponownie zaindeksuj zaktualizowany plik.

Następne kroki

• Konfigurowanie indeksatorów obiektów blob
• Definiowanie mapowań pól
• Omówienie indeksatorów
• Jak indeksować obiekty blob CSV za pomocą indeksatora obiektów blob
• Tutorial: wyszukaj dane języka Markdown z Azure Blob Storage