Azure AI Search: SharePoint mit LoyJoy integrieren

Der Aufbau einer Retrieval-Augmented-Generation-Pipeline (RAG) mit Embeddings ist eine leistungsstarke Möglichkeit, die Fähigkeit Ihrer KI zu verbessern, relevante, faktenbasierte Antworten auf Basis Ihrer eigenen Datenquellen wie Microsoft SharePoint zu liefern. SharePoint beherbergt oft wertvolles organisatorisches Wissen und Dokumente, aber der Echtzeitzugriff auf diese unstrukturierten Daten für KI-gestützte Lösungen kann eine Herausforderung sein. Durch die Erstellung einer RAG-Pipeline können Sie SharePoint-Daten indexieren, um sie durchsuchbar zu machen, und die Antworten Ihres KI-Modells mit aktuellen, kontextbewussten Informationen anreichern.

In diesem Blogbeitrag geben wir eine Schritt-für-Schritt-Anleitung zum Aufbau einer RAG-Pipeline in Azure und zeigen, wie Sie Azure AI Search mit Ihren SharePoint-Daten integrieren. Dies ermöglicht Ihrer KI, die relevantesten Informationen direkt aus SharePoint abzurufen und verbessert die Genauigkeit und Relevanz der erzeugten Antworten. Sie finden eine detaillierte Beschreibung der gesamten Einrichtung unter Verwendung der integrierten Embedding-Erzeugungs- und Abruffunktionen.

Und das Beste daran? All dies lässt sich nahtlos in die LoyJoy-Plattform integrieren, sodass Sie mit generativer KI ganz einfach Ihren eigenen KI-Agenten erstellen und Ihren Kunden ein nahtloses Erlebnis bieten können.

Beachten Sie, dass Sie API-Aufrufe an den Azure-AI-Search-Dienst tätigen müssen, um die Pipeline einzurichten. Als Alternative zur Verwendung von curl können Sie auch unsere Postman-Collection für diese API-Aufrufe verwenden.

Voraussetzungen

• SharePoint-Konto mit Zugriff auf die Website, die Sie indexieren möchten.
• Azure-Konto mit Zugriff auf Azure AI Search, das mit dem Microsoft-SharePoint-Konto verknüpft ist.
• Ein Azure-OpenAI-Embedding-Service, z. B. mit text-embedding-ada-002 oder einem ähnlichen Modell.

Schritt 1: Azure AI Search einrichten

Erstellen Sie im Microsoft-Azure-Portal eine neue Azure-AI-Search-Ressource. Sie finden diese unter dem Abschnitt "Create a resource". Wählen Sie einen eindeutigen Namen und notieren Sie ihn, geben Sie einen passenden Standort und einen Tarif für Ihre Ressource an. Beachten Sie, dass dieser mindestens "Basic" sein muss, um Ihre SharePoint-Daten zu indexieren.

Schritt 2: Den API-Schlüssel Ihrer Azure-AI-Search-Ressource notieren

Sobald Ihre Azure-AI-Search-Ressource erstellt ist, notieren Sie Ihren Primary admin key, indem Sie zu Settings -> Keys navigieren. Sie benötigen diese später zum Erstellen Ihrer AI-Search-Ressourcen. Navigieren Sie schließlich zu Settings -> Identity und aktivieren Sie System-Assigned Managed Identity.

Schritt 3: Eine Microsoft-Entra-Anwendungsregistrierung erstellen

Der SharePoint-Online-Indexer verwendet diese Microsoft-Entra-Anwendung zur Authentifizierung. Führen Sie die folgenden Schritte aus, um eine Anwendungsregistrierung im Azure-Portal zu erstellen. Alternativ folgen Sie den Schritten in der offiziellen Microsoft-Dokumentation.

1. Suchen Sie nach Microsoft Entra ID oder navigieren Sie dorthin, und wählen Sie dann App registrations.
2. Wählen Sie + New registration.

• Geben Sie einen Namen für Ihre App an.
• Wählen Sie Single tenant.
• Überspringen Sie den Schritt zur URI-Angabe. Keine Redirect-URI erforderlich.
• Wählen Sie Register.

3. Notieren Sie Ihre Application (client) ID.
4. Wählen Sie links API permissions, dann Add a permission, dann Microsoft Graph und fügen Sie Folgendes hinzu:

• Application - Files.Read.All
• Application - Sites.Read.All

5. Wählen Sie nach dem Hinzufügen der Berechtigungen Grant admin consent for [Ihre Organisation].
6. Wählen Sie den Tab Authentication.
7. Setzen Sie Allow public client flows auf Yes und wählen Sie dann Save.
8. Wählen Sie + Add a platform, dann Mobile and desktop applications, aktivieren Sie https://login.microsoftonline.com/common/oauth2/nativeclient, und wählen Sie dann Configure.
9. Wählen Sie links Certificates & secrets, dann + New client secret.

• Geben Sie eine Beschreibung an.
• Wählen Sie einen Ablaufzeitraum.
• Wählen Sie Add.

10. Das neue Application secret erscheint in der Geheimnisliste. Sobald Sie die Seite verlassen, ist das Geheimnis nicht mehr sichtbar. Kopieren Sie es daher mit der Kopierschaltfläche und speichern Sie es an einem sicheren Ort.

Schritt 4: Datenquelle erstellen

Ab diesem Abschnitt verwenden Sie für die restlichen Schritte eine Preview-REST-API. Wir empfehlen die neueste Preview-API-Version. Eine Beispiel-URL für eine SharePoint-Website ist https://microsoft.sharepoint.com/teams/MySharePointSite. Sie erhalten den Endpunkt, indem Sie zur Startseite Ihrer SharePoint-Website navigieren und die URL aus dem Browser kopieren.

Beachten Sie, dass Sie im Container-Parameter den Namen der SharePoint-Bibliothek angeben können, die Sie indexieren möchten. Wenn Sie die Standardbibliothek der SharePoint-Website indexieren möchten, können Sie als Containernamen defaultSiteLibrary festlegen. Weitere Informationen hier

curl --location 'https://[Azure AI service name].search.windows.net/datasources?api-version=[Api version]' \
--header 'api-key: [Primary Admin key]' \
--header 'Content-Type: application/json' \
--data '{
    "name" : "sharepoint-datasource",
    "type" : "sharepoint",
    "credentials" : { "connectionString" : "SharePointOnlineEndpoint=[Sharepoint site url];ApplicationId=[Application (client) ID];ApplicationSecret=[Application secret];" },
    "container" : { "name" : "defaultSiteLibrary", "query" : null }
}'

Schritt 5: Einen Index erstellen

Erstellen Sie einen Index, um die Daten Ihrer SharePoint-Website zu speichern. Das folgende Beispiel erstellt einen Index namens sharepoint-index mit Feldern für die Metadaten der SharePoint-Elemente, den Inhalt ihrer Abschnitte und ihre Embeddings. Beachten Sie, dass das Feld metadata_spo_item_weburi verwendet wird, um die URL des SharePoint-Elements zu speichern. Es kann nur verwendet werden, wenn der Benutzer Zugriff auf die SharePoint-Website hat.

curl --location 'https://[Azure AI search service name].search.windows.net/indexes?api-version=[Api version]' \
--header 'api-key: [Primary Admin key]' \
--header 'Content-Type: application/json' \
--data '{
    "name" : "sharepoint-index",
    "fields": [
        { "name": "id", "type": "Edm.String", "key": true, "searchable": true, "analyzer": "keyword" },
        { "name": "metadata_spo_item_name", "type": "Edm.String", "key": false, "searchable": true, "filterable": false, "sortable": false, "facetable": false },
        { "name": "metadata_spo_item_path", "type": "Edm.String", "key": false, "searchable": false, "filterable": false, "sortable": false, "facetable": false },
        { "name": "metadata_spo_item_content_type", "type": "Edm.String", "key": false, "searchable": false, "filterable": true, "sortable": false, "facetable": true },
        { "name": "metadata_spo_item_last_modified", "type": "Edm.DateTimeOffset", "key": false, "searchable": false, "filterable": false, "sortable": true, "facetable": false },
        { "name": "metadata_spo_item_size", "type": "Edm.Int64", "key": false, "searchable": false, "filterable": false, "sortable": false, "facetable": false },
        { "name": "metadata_spo_item_weburi", "type": "Edm.String", "key": false, "searchable": false, "filterable": false, "sortable": false, "facetable": false },
        { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false },
        { "name": "parent_key", "type": "Edm.String", "filterable": true },
        { "name": "embedding", "type": "Collection(Edm.Single)", "searchable": true, "dimensions": 1536, "vectorSearchProfile": "vectorizer-embedding" }
    ],
    "vectorSearch": {
      "profiles": [
        {
          "name": "vectorizer-embedding",
          "algorithm": "hsnw-1",
          "vectorizer": "embedding-vectorizer"
        }
      ],
      "algorithms": [
        {
          "name": "hsnw-1",
          "kind": "hnsw",
          "hnswParameters": {
            "m": 4,
            "efConstruction": 400,
            "efSearch": 500,
            "metric": "cosine"
          }
        }
      ],
      "vectorizers": [
        {
          "name": "embedding-vectorizer",
          "kind": "azureOpenAI",
          "azureOpenAIParameters": {
            "resourceUri": "[Embedding resource url]",
            "deploymentId": "[Embedding deployment id]",
            "modelName": "[Embedding model name]",
            "apiKey": "[Embedding api key]"
          }
        }
      ]
    }
}
'

Die folgenden optionalen Felder können Teil des Index sein und dienen als Metadaten für den Prompt: metadata_author, metadata_author_email, metadata_created_by, metadata_modified_by, metadata_modified_by_email.

Schritt 6: Ein Skillset erstellen

Erstellen Sie ein Skillset, um den Inhalt der SharePoint-Elemente in Abschnitte zu unterteilen und für jeden Abschnitt Embeddings zu erzeugen. Das folgende Beispiel erstellt ein Skillset namens chunk-and-embed mit drei Skills: Eine LanguageDetectionSkill zum Erkennen der Sprache des Dokuments, eine SplitSkill zum Aufteilen des Dokumentinhalts in Abschnitte und eine AzureOpenAIEmbeddingSkill zum Erzeugen von Embeddings für jeden Abschnitt.

curl --location --request PUT 'https://[Azure AI service name].search.windows.net/skillsets/chunk-and-embed?api-version=[Api version]' \
--header 'api-key: [Primary Admin key]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "@odata.context": "https://[Azure AI service name].search.windows.net/$metadata#skillsets/$entity",
  "@odata.etag": "\"0x8DCD2580917230A\"",
  "name": "chunk-and-embed",
  "description": null,
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
      "name": "LanguageDetectionSkill",
      "context": "/document",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "languageCode",
          "targetName": "language"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
      "name": "SplitSkill",
      "context": "/document",
      "defaultLanguageCode": "en",
      "textSplitMode": "pages",
      "maximumPageLength": 800,
      "pageOverlapLength": 0,
      "maximumPagesToTake": 0,
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        },
        {
          "name": "languageCode",
          "source": "/document/language"
        }
      ],
      "outputs": [
        {
          "name": "textItems",
          "targetName": "chunks"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
      "name": "AzureOpenAIEmbeddingSkill",
      "context": "/document/chunks/*",
      "resourceUri": "[Embedding resource url]",
      "apiKey": "[Embedding api key]",
      "deploymentId": "[Embedding deployment id]",
      "modelName": "[Embedding model name]",
      "dimensions": 1536,
      "inputs": [
        {
          "name": "text",
          "source": "/document/chunks/*"
        }
      ],
      "outputs": [
        {
          "name": "embedding",
          "targetName": "embedding"
        }
      ]
    }
  ],
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "sharepoint-index",
        "parentKeyFieldName": "parent_key",
        "sourceContext": "/document/chunks/*",
        "mappings": [
          {
            "name": "content",
            "source": "/document/chunks/*"
          },
          {
            "name": "metadata_spo_item_name",
            "source": "/document/metadata_spo_item_name"
          },
          {
            "name": "metadata_spo_item_path",
            "source": "/document/metadata_spo_item_path"
          },
          {
            "name": "metadata_spo_item_content_type",
            "source": "/document/metadata_spo_item_content_type"
          },
          {
            "name": "metadata_spo_item_last_modified",
            "source": "/document/metadata_spo_item_last_modified"
          },
          {
            "name": "metadata_spo_item_size",
            "source": "/document/metadata_spo_item_size"
          },
          {
            "name": "metadata_spo_item_weburi",
            "source": "/document/metadata_spo_item_weburi"
          },
          {
            "name": "embedding",
            "source": "/document/chunks/*/embedding"
          }
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}'

Schritt 7: Einen Indexer erstellen

Erstellen Sie einen Indexer, um den Index mit Daten von der SharePoint-Website zu befüllen. Ein Indexer ist ein Pull-Modell, das den Index verwaltet und Änderungen automatisch erkennt. Er ist so geplant, dass er stündlich ausgeführt wird. Beachten Sie, dass seit dem 09.12.2024 das inkrementelle Cache-Enrichment von Azure nicht empfohlen wird.

curl --location 'https://[Azure AI service name].search.windows.net/indexers?api-version=[Api version]' \
--header 'api-key: [Primary admin key]' \
--header 'Content-Type: application/json' \
--data '{
    "name": "sharepoint-indexer",
    "dataSourceName": "sharepoint-datasource",
    "targetIndexName": "sharepoint-index",
    "skillsetName": "chunk-and-embed",
    "schedule": {
      "interval": "PT1H",
      "startTime": "2024-09-01T08:00:00.7Z"
    },
    "parameters": {
      "batchSize": null,
      "maxFailedItems": null,
      "maxFailedItemsPerBatch": null,
      "base64EncodeKeys": null,
      "configuration": {
        "indexedFileNameExtensions": ".pdf, .docx",
        "excludedFileNameExtensions": ".png, .jpg",
        "dataToExtract": "contentAndMetadata"
      }
    },
    "fieldMappings": [
      {
        "sourceFieldName": "metadata_spo_site_library_item_id",
        "targetFieldName": "id",
        "mappingFunction": {
          "name": "base64Encode"
        }
      }
    ]
}'

Wenn Sie den Indexer zum ersten Mal erstellen, wartet die Anfrage Create Indexer (preview), bis Sie den nächsten Schritt abgeschlossen haben. Sie müssen Get Indexer Status aufrufen, um den Link zu erhalten und Ihren neuen Gerätecode einzugeben.

curl --location 'https://[Azure AI service name].search.windows.net/indexers/sharepoint-indexer/status?api-version=[Api version]' \
--header 'api-key: [Primary admin key]' \
--header 'Content-Type: application/json'

Kopieren Sie den Gerätelogin-Code aus der Antwort von Get Indexer Status. Der Gerätelogin befindet sich in der "errorMessage".

{
  "lastResult": {
    "status": "transientFailure",
    "errorMessage": "To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code <CODE> to authenticate."
  }
}

Das war's! Sie haben nun eine RAG-Pipeline in Azure eingerichtet, die Azure AI Search mit Ihren SharePoint-Daten integriert. Sie können nun die Azure-AI-Search-API verwenden, um Ihre SharePoint-Daten abzufragen und die relevantesten Informationen direkt aus SharePoint abzurufen.

Schritt 8: Mit LoyJoy integrieren

Jetzt ist es an der Zeit, Azure AI Search in LoyJoy zu integrieren. Um LoyJoy den Zugriff auf Ihre Azure-AI-Search-Ressourcen zu autorisieren, müssen Sie im Azure-Portal einen neuen Query-API-Schlüssel erstellen. Navigieren Sie zu Ihrer Azure-AI-Search-Ressource, dann zu Settings -> Keys und erstellen Sie einen neuen Query-Schlüssel.

Fügen Sie in Ihrem LoyJoy-KI-Agenten das Azure-AI-Search-Tool zu einem KI-Agent-Modul hinzu oder konfigurieren Sie den Suchanbieter im AI-Knowledge-Modul. Geben Sie den in Schritt 1 erstellten Azure-AI-Search-Dienstnamen ein, fügen Sie Ihren Indexnamen (sharepoint-index) ein und fügen Sie den soeben erstellten Query-Schlüssel ein.

gefahr

Jeder LoyJoy-Chat-KI-Agent ist standardmäßig vom öffentlichen Internet aus erreichbar. Wenn SharePoint sensible oder interne Informationen enthält, die nicht öffentlich sein sollen, MUSS der Zugriff auf den Chat auf bestimmte IP-Adressen beschränkt werden. Dies kann erreicht werden, indem in den LoyJoy-Tenant-Einstellungen bestimmte erlaubte IP-Adressen, z. B. die Ihres Firmennetzwerks, konfiguriert werden.