Transferir dados do SharePoint para uma base de conhecimento RAGFlow do DTS - Data Transmission Service: Central de Documentação do Alibaba Cloud

Pré-requisitos

Você já criou uma base de conhecimento RAGFlow no DTS e configurou uma lista de permissões de IP.

Tipos de dados compatíveis

O RAGFlow do DTS permite a ingestão de arquivos de bibliotecas de documentos do SharePoint, incluindo arquivos Word, Excel, PDF e PowerPoint.

Antes de começar

Etapa 1: Registrar um aplicativo no Microsoft Entra ID

Faça login no portal do Azure.
No painel de navegação à esquerda, selecione Microsoft Entra ID.
Clique em App registrations > New registration.

Insira as informações do aplicativo e clique em Register.

Parâmetro	Descrição
Name	Insira um nome para o aplicativo, como `KBSync-SharePoint-Reader`.
Supported account types	Selecione Accounts in this organizational directory only (Single tenant).
Redirect URI	Deixe este campo em branco. O fluxo de credenciais do cliente não exige uma URI de redirecionamento.

Após o registro, anote as seguintes informações na página Overview do aplicativo.

Parâmetro	Descrição
Application (client) ID	Identificador exclusivo do aplicativo, correspondente ao parâmetro `llamahubReader_client_id` na configuração do KBSync.
Directory (tenant) ID	ID do locatário do Microsoft Entra, correspondente ao parâmetro `llamahubReader_tenant_id` na configuração do KBSync.

Etapa 2: Criar um segredo do cliente

Na página do aplicativo, selecione Certificates & secrets > Client secrets.
Clique em New client secret.
Insira uma descrição e selecione um período de expiração (recomendamos 24 months ou Never).
Clique em Add e copie imediatamente o valor do segredo.

Importante
Não é possível visualizar novamente esse valor após sair da página. Certifique-se de copiá-lo e salvá-lo com segurança logo após a criação. Essa chave corresponde ao parâmetro llamahubReader_client_secret na configuração do KBSync.

Etapa 3: Configurar permissões de API

Na página do aplicativo, selecione API permissions > Add a permission.
Selecione Microsoft Graph > Application permissions.

Pesquise e adicione as seguintes permissões.

Tipo de permissão	Nome da permissão	Descrição
Application	`Sites.Read.All` ou `Sites.Selected`	`Sites.Read.All`: Lê todos os sites do SharePoint (recomendado para acesso completo ao site). `Sites.Selected`: Lê apenas sites selecionados do SharePoint (opção mais segura). Nota Se você selecionar a permissão `Sites.Selected`, será necessário conceder acesso explicitamente a sites específicos do SharePoint para seu aplicativo via API Microsoft Graph.
Application	`Files.Read.All`	Permite que o aplicativo leia todos os arquivos em todas as coleções de sites.
Application	`BrowserSiteLists.Read.All`	Permite que o aplicativo leia listas de sites do navegador.

Conceda consentimento de administrador.
Após adicionar as permissões, um administrador global deve conceder consentimento para ativá-las.
1. Na página API permissions, clique em Grant admin consent for <tenant name>.
2. Verifique se a coluna Status exibe Granted para as permissões.
Nota
Caso não possua privilégios de administrador, entre em contato com o administrador global do Microsoft 365 da sua organização para concluir esta etapa.

Etapa 4: Obter informações do site do SharePoint

Antes de configurar o KBSync, reúna as seguintes informações do SharePoint.

Parâmetro	Descrição	Como obter
Nome do site	Nome do site do SharePoint.	Extraído da URL do SharePoint. Por exemplo, se a URL for `https://contoso.sharepoint.com/sites/Marketing`, o nome do site é `Marketing`.
Caminho da pasta	Caminho para uma pasta dentro da biblioteca de documentos.	No SharePoint, visualize o caminho da pasta do documento de destino. Por exemplo, `Reports`.
Nome do host	Nome do host do SharePoint. Obrigatório ao usar a permissão `Sites.Selected`.	Extraído da URL do SharePoint. Por exemplo, `contoso.sharepoint.com`.
Nome da unidade	Nome da biblioteca de documentos do SharePoint.	Visualize o nome da biblioteca de documentos no site do SharePoint. A biblioteca padrão geralmente é `Documents`.

Procedimento

Etapa 1: Preparar o arquivo de configuração

Obtenha o programa KBSync e prepare seu ambiente de execução.
Nota
- Envie um ticket para obter o arquivo KBSync.
- O programa KBSync requer um ambiente Linux com acesso tanto à API Microsoft Graph quanto ao RAGFlow.

Prepare o arquivo de configuração chamado config.

Crie um arquivo chamado config no seu ambiente Linux.

Copie o código abaixo para o arquivo config.

# Basic configuration
sourceType=LlamaHub
sinkType=RagFlowV2
whiteList=
blackList=

sleepTime=600
jobId=dts_kbsync_llamahub_sharepoint_to_ragflow
documentSyncMode=full

# LlamaHub Reader configuration
llamahubReaderClass=llama_index.readers.microsoft_sharepoint.SharePointReader
llamahubReader_client_id=96b75717-****-****-****-46b70e29bec1
llamahubReader_tenant_id=c2211d60-****-****-****-fd062b3f8c2b
llamahubReader_client_secret=Xwd8Q***************DmpRTDmpRTw
llamahubReader_sharepoint_host_name=contoso.sharepoint.com
llamahubReader_sharepoint_site_name=Marketing
llamahubReader_drive_name=Documents
llamahubLoad_sharepoint_folder_path=Reports

# Sink RAGFlow configuration
sinkOSSAccessKeyId=
sinkOSSAccessKeySecret=
sinkOSSRegion=
sinkOSSBucket=
sinkOSSEndpoint=

Atualize os parâmetros no arquivo config.

Importante

Se um parâmetro não for necessário para sua configuração, deixe seu valor vazio.
O parâmetro blackList tem prioridade maior que o parâmetro whiteList.

Parâmetro	Obrigatório	Descrição	Como obter
`whiteList`	Não	Especifica caminhos a incluir (lista de permissões) ou excluir (lista de bloqueios) da sincronização. Nota Suporta expressões regulares. Separe vários caminhos com espaços.	Obtenha os caminhos das pastas de destino no SharePoint.
`blackList`	Não		Obtenha os caminhos das pastas de destino no SharePoint.
`sourceType`	Sim	Tipo da origem.	Defina o valor como `LlamaHub`.
`sinkType`	Sim	Tipo do destino.	Defina o valor como `RagFlowV2`.
`sleepTime`	Sim	Intervalo em segundos para varreduras incrementais.	-
`documentSyncMode`	Sim	Modo de sincronização: `full`: Sincronização completa `inc`: Sincronização incremental	-
`llamahubReader_client_id`	Sim	Application (client) ID do aplicativo registrado no Microsoft Entra ID.	Consulte Etapa 1: Registrar um aplicativo no Microsoft Entra ID.
`llamahubReader_tenant_id`	Sim	Directory (tenant) ID do Microsoft Entra ID.
`llamahubReader_client_secret`	Sim	Segredo do cliente criado no Microsoft Entra ID.	Consulte Etapa 2: Criar um segredo do cliente.
`llamahubReader_sharepoint_site_name`	Sim	Nome do site do SharePoint.	Consulte Etapa 4: Obter informações do site do SharePoint.
`llamahubReader_sharepoint_host_name`	Não Nota Obrigatório ao usar a permissão `Sites.Selected`.	Nome do host do SharePoint.
`llamahubReader_drive_name`	Não	Nome da biblioteca de documentos do SharePoint. O valor padrão é `Documents`.
`llamahubLoad_sharepoint_folder_path`	Não	Caminho para uma pasta dentro da biblioteca de documentos. Se deixado em branco, o sistema sincroniza todo o conteúdo na raiz da biblioteca.
`sinkOSSAccessKeyId`	Sim	Informações relacionadas ao bucket do Object Storage Service (OSS).	Obtenha essas informações no console do Object Storage Service (OSS).
`sinkOSSAccessKeySecret`	Sim
`sinkOSSRegion`	Sim
`sinkOSSBucket`	Sim
`sinkOSSEndpoint`	Sim

Configuração avançada

Configure as opções avançadas abaixo conforme necessário:

Opção	Descrição	Padrão
Recursive	Define se as subpastas devem ser percorridas recursivamente.	`true`
File filter	Filtragem por tipo de arquivo (por exemplo, sincronizar apenas `.pdf`, `.docx`)	Sem filtro
sinkFailOnError	Define se o processo de sincronização deve parar quando ocorrer um erro.	`false` (Registra o erro em log e continua)

Etapa 2: Executar o programa KBSync

Coloque o arquivo KBSync e o arquivo config no mesmo diretório do seu ambiente Linux.
No ambiente Linux, execute o comando ./KBSync --config config para iniciar o programa KBSync.

Solução de problemas

Mensagem de erro	Causa possível	Solução
`Authentication failed`	O segredo do cliente está incorreto ou expirou.	Verifique o Application (client) ID e o segredo do cliente. Se o segredo tiver expirado, crie um novo no portal do Azure.
`Access denied`	As permissões de API necessárias não foram concedidas ou falta o consentimento do administrador.	Certifique-se de ter adicionado todas as permissões de API necessárias e concedido o consentimento do administrador. Na página API permissions do portal do Azure, verifique se o status é Granted.
`Site not found`	O nome do site ou a URL está configurado incorretamente.	Verifique se o nome e o caminho do site do SharePoint estão corretos e se o parâmetro `llamahubReader_sharepoint_site_name` está definido com o nome do site, e não com a URL completa.
`Insufficient privileges`	O aplicativo não tem permissão para acessar o site especificado.	Ao usar a permissão `Sites.Selected`, é necessário conceder explicitamente acesso aos sites de destino usando a API Microsoft Graph. Consulte as instruções em Configurar permissões de API para concluir a autorização no nível do site.

Apêndice: Conceder permissões no nível do site

Use a API Microsoft Graph para conceder a permissão Sites.Selected a sites específicos. O console do Azure não oferece suporte à autorização por site individual.

No Graph Explorer, faça login com uma conta de administrador global e conceda a permissão Sites.FullControl.All para a sessão atual.

Insira qualquer solicitação. Clique na aba Modify permissions acima, localize Sites.FullControl.All e clique em Consent para concluir a autorização.
Obtenha o ID do site do SharePoint de destino executando a seguinte solicitação no Graph Explorer:
```
GET https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}
```
Por exemplo: GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/project-alpha. O campo id na resposta é o ID do site.

Conceda acesso ao site específico para seu aplicativo executando a seguinte solicitação POST no Graph Explorer:

POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions
Content-Type: application/json

{
  "roles": ["write"],
  "grantedToIdentities": [
    {
      "application": {
        "id": "<your application's Application (client) ID>",
        "displayName": "<your application's name>"
      }
    }
  ]
}

Os valores válidos para roles são: read (somente leitura), write (leitura e gravação) e owner (controle total).

Verifique se as permissões entraram em vigor. Execute GET https://graph.microsoft.com/v1.0/sites/{site-id}/permissions e confirme se a resposta contém seu aplicativo e suas informações de função.