Sync DingTalk data to a DTS RAGFlow knowledge base - 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 suportados

Método MCP

O DTS RAGFlow conecta-se aos documentos em uma base de conhecimento do DingTalk por meio do protocolo MCP. A tabela a seguir descreve o processamento de cada tipo de documento:

Tipo de documento	Extensão de arquivo	Método de processamento
Documento online	`adoc`	Busca o conteúdo Markdown usando o DingTalk Docs MCP e faz upload para o RAGFlow no formato `.md`.
Planilha	`axls`	Obtém dados pelo DingTalk Sheets MCP, exporta para o formato `.csv` e envia para o RAGFlow. Se o parâmetro `dingDingSheetMcpEndpoint` não estiver configurado, arquivos desse tipo serão ignorados.
Anexo comum	Outros	Baixe o arquivo original via Docs MCP e faz upload no RAGFlow.
Apresentação, mapa mental, quadro branco, tabela multidimensional	`appt`, `amind`, `adraw`, `able`	Não suportado. Marcado como `unsupported-source-type` e registrado no checkpoint.

Método DingTalk Drive

O DTS RAGFlow conecta-se aos seguintes tipos de arquivos no DingTalk Drive:

Arquivos Word, Excel e PowerPoint criados no DingTalk Drive.
Arquivos enviados ao DingTalk Drive, como TXT, PDF e Markdown.

Antes de começar

O DTS oferece dois métodos para conexão com uma fonte de dados do DingTalk. Escolha a opção que melhor atende às suas necessidades:

Método MCP (Recomendado): Conecta-se via protocolo MCP. Esta opção dispensa a criação de aplicativos, tem configuração simplificada e oferece melhor desempenho.
Método DingTalk Drive: Conecta-se pela API da plataforma aberta do DingTalk. Suporta arquivos do DingTalk Drive, mas exige a criação de um aplicativo no DingTalk e a configuração das respectivas permissões.

Método MCP

Etapa 1: Obter o endpoint do servidor MCP

Documentos online e planilhas do DingTalk usam servidores MCP distintos. Ative cada service e obtenha o respectivo endpoint.

Acesse o DingTalk MCP Marketplace e ative os seguintes serviços MCP:
- DingTalk Docs MCP (Obrigatório): Permite ler o conteúdo de documentos e baixe arquivos. Ative este service em: DingTalk Docs MCP.
- DingTalk Sheets MCP (Opcional): Permite ler dados de planilhas. Se este service não for ativado, as planilhas na base de conhecimento serão ignoradas. Ative-o em: DingTalk Sheets MCP.
Na página de detalhes do service no MCP Marketplace, copie o Streamable-HTTP Endpoint.
```
https://mcp-gw.dingtalk.com/server/<server_id>?key=<key>
```

Importante

O parâmetro key no endpoint é uma credencial de acesso. Mantenha-a segura e evite confirmá-la (commit) em repositórios Git ou expô-la em canais públicos.

Etapa 2: Obter o WorkSpaceId

O WorkSpaceId é o identificador único de uma base de conhecimento do DingTalk. Para obtê-lo, use a URL da página inicial da base de conhecimento.

Abra a página inicial da base de conhecimento desejada do DingTalk no navegador.
```
https://alidocs.dingtalk.com/i/space/{WorkSpaceId}
```
Copie a parte {WorkSpaceId} da URL. Por exemplo, se a URL for https://alidocs.dingtalk.com/i/space/nb9XJj73Oxxxx, o WorkSpaceId será nb9XJj73Oxxxx.

Etapa 3: Obter RootFolderIds (Opcional)

Para sincronizar apenas subdiretórios específicos em vez de toda a base de conhecimento, obtenha os IDs de nó desses subdiretórios. Sem essa configuração, o KBSync percorre recursivamente todos os nós a partir do diretório raiz.

Na interface web da base de conhecimento do DingTalk, abra o subdiretório alvo.
```
https://alidocs.dingtalk.com/i/nodes/{nodeId}
```
Copie a parte {nodeId} da URL. Para sincronizar vários subdiretórios, separe os IDs de nó com vírgulas.

Método DingTalk Drive

Etapa 1: Crie um aplicativo DingTalk

Faça login na Plataforma Aberta do DingTalk e acesse o backend do desenvolvedor.
Crie um aplicativo.
1. No canto superior direito da página, clique em My Console.
2. Clique na aba App Development. No painel de navegação à esquerda, escolha Internal Enterprise Applications > DingTalk Applications.
3. Clique em Create App.
4. Insira um App Name e uma App Description e clique em Save.
5. À direita do aplicativo, clique em > App Details.
6. No painel de navegação à esquerda, escolha Basic Information> Credentials & Basic Info.
7. Na seção App Credentials, anote o Client ID e o Client Secret.
Configure as permissões. No painel de navegação à esquerda, escolha Development Configuration > Permission Management e selecione as seguintes permissões:
- Permissão de leitura para espaço em disco do aplicativo
- Permissão de leitura para informações de membros
- Permissão de leitura para arquivos de armazenamento corporativo
- Permissão de leitura para informações de download de arquivos de armazenamento corporativo
Clique em Bulk Application.

Etapa 2: Obter o UserID do funcionário

Faça login no Console de Administração do DingTalk usando uma conta DingTalk com permissões de administrador empresarial ou de equipe.
No painel de navegação à esquerda, escolha Contacts > Member Management.
Selecione um departamento e anote o UserID do funcionário da conta DingTalk desejada.

Importante
A conta DingTalk precisa ter permissões de gerenciamento sobre os arquivos alvo no DingTalk Drive para poder visualize-os e baixe-os.

Procedimento

Obtenha o arquivo KBSync.

Nota
Entre no grupo do DingTalk (ID: 79690034672) e contate o suporte técnico para receber o arquivo KBSync.
Configure o ambiente de execução do KBSync.

Nota
O programa KBSync requer um ambiente Linux com acesso de rede tanto ao service DingTalk MCP quanto ao service RAGFlow.

Prepare o arquivo config.

Crie um arquivo de sistema Linux chamado config.

Copie o código abaixo para o arquivo config.

Método MCP

whiteList=
blackList=
sinkType=RagFlowV2
sourceType=DingDingV3
ragflowUrl=http://XX.XX.XX.XX
ragflowApiKey=Bearer ragflow-Rh******BiYWY3MDAxNj
ragflowDatasetId=b2af7c4c******dbae
dingDingMcpEndpoint=https://mcp-gw.dingtalk.com/server/<server_id>?key=<key>
dingDingSheetMcpEndpoint=https://mcp-gw.dingtalk.com/server/<server_id>?key=<key>
dingDingWorkSpaceId=nb9XJj73Oxxxx
dingDingRootFolderIds=

Método DingTalk Drive

whiteList=
blackList=
sinkType=RagFlowV2
sourceType=DingDingV2
ragflowUrl=http://XX.XX.XX.XX
ragflowApiKey=Bearer ragflow-Rh******BiYWY3MDAxNj
ragflowDatasetId=b2af7c4c******dbae
dingDingClientId=dingz******k66u
dingDingClientSecret=sa4vI******xrJT-OmEf_fgF0GpbKi4L******tzugFn-_
dingDingUserId=012******815010

Substitua os valores dos parâmetros no arquivo config.

Importante

Deixe vazios os valores dos parâmetros que não exigem configuração.
O parâmetro blackList tem precedência sobre o parâmetro whiteList.

Parâmetro	Obrigatório	Descrição	Como obter
`whiteList`	Não	Caminhos dos documentos na base de conhecimento a serem incluídos (lista de permissões) ou excluídos (lista de bloqueios). Nota Expressões regulares são suportadas. Separe vários caminhos com espaços.	Obtenha os caminhos na sua base de conhecimento do DingTalk.
`blackList`	Não
`sinkType`	Sim	Tipo do destino (sink).	Defina como `RagFlowV2`.
`sourceType`	Sim	Tipo da fonte (source).	Para o método DingTalk Drive, defina como `DingDingV2`. Para o método MCP, defina como `DingDingV3`.
`ragflowUrl`	Sim	URL da sua instância RAGFlow (o servidor de API).	Obter a URL do servidor de API da base de conhecimento RAGFlow.
`ragflowApiKey`	Sim	Chave de API para a base de conhecimento RAGFlow.	Obter a chave de API para a base de conhecimento RAGFlow.
`ragflowDatasetId`	Sim	ID da base de conhecimento RAGFlow.	Obter o ID da base de conhecimento RAGFlow.
`dingDingClientId`	Sim (método DingTalk Drive)	Client ID do aplicativo DingTalk. Necessário apenas para o método DingTalk Drive.	Obtido em Antes de começar - Método DingTalk Drive.
`dingDingClientSecret`	Sim (método DingTalk Drive)	Client Secret do aplicativo DingTalk. Necessário apenas para o método DingTalk Drive.	Obtido em Antes de começar - Método DingTalk Drive.
`dingDingUserId`	Sim (método DingTalk Drive)	UserID do funcionário da conta DingTalk usada para exportar arquivos do DingTalk Drive. Necessário apenas para o método DingTalk Drive.	Obtido em Antes de começar - Método DingTalk Drive.
`dingDingMcpEndpoint`	Sim (método MCP)	URL do endpoint para o DingTalk Docs MCP, usada para ler conteúdo de documentos online e baixe anexos. Necessária apenas para o método MCP.	Obter o endpoint do servidor MCP.
`dingDingSheetMcpEndpoint`	Não (método MCP)	URL do endpoint para o DingTalk Sheets MCP, usada para ler dados de planilhas. Necessária apenas para o método MCP. Se não configurada, arquivos do tipo `axls` serão ignorados e gravados no checkpoint.	Obter o endpoint do servidor MCP.
`dingDingWorkSpaceId`	Sim (método MCP)	ID da base de conhecimento alvo do DingTalk. Necessário apenas para o método MCP.	Obter o WorkSpaceId.
`dingDingRootFolderIds`	Não (método MCP)	IDs dos diretórios raiz a serem sincronizados. Separe vários IDs com vírgulas. Se não configurado, o KBSync sincroniza toda a base de conhecimento.	Obter RootFolderIds.

Coloque o arquivo KBSync e o arquivo de configuração config no mesmo diretório em um ambiente Linux.
No seu ambiente Linux, execute o comando ./KBSync --config config para iniciar o programa KBSync.

Método MCP

Aguarde o programa KBSync sincronizar os dados. Se a saída for semelhante à abaixo, a conexão foi estabelecida com sucesso e o processo de sincronização começou.

./KBSync --config config
 
INFO config SourceType=DingDingV3, SinkType=RagFlowV2
INFO config whiteList=, blackList=
INFO config ragflowUrl=http://XX.XX.XX.XX, ragflowApiKey=Bearer ragflow-RhMjc0NjFhNTZmNTExZjBiYWY****
INFO config ragflowDatasetId=b2af7c4c56f511f0a3d700163e****
INFO config dingDingMcpEndpoint=https://mcp-gw.dingtalk.com/server/<server_id>?key=****
INFO config dingDingSheetMcpEndpoint=https://mcp-gw.dingtalk.com/server/<server_id>?key=****
INFO config dingDingWorkSpaceId=nb9XJj73Ox37lXyA
INFO Verifying RAGFlow connection...
INFO Attempting to list datasets to validate the connection...
INFO Successfully found matching dataset: Name='test', ID='b2af7c4c56f511f0a3d700163e****'
INFO RAGFlow connection verified successfully.
INFO Starting DingTalk MCP connection...
INFO MCP connection established successfully.
INFO Listing workspace nodes...
INFO Found 42 nodes in workspace.
INFO Syncing documents...

Nota

O programa KBSync roda continuamente e sincroniza dados periodicamente. Pare ou reinicie o programa manualmente conforme necessário.

Método DingTalk Drive

Execute o programa KBSync.

Nota
O programa KBSync sincroniza periodicamente os dados dos documentos alvo. Configure o intervalo de sincronização ou pare e reinicie o programa manualmente quando precisar.

Insira 2 e pressione Enter.

Aguarde o programa KBSync sincronizar os dados. Se a saída se assemelhar ao exemplo abaixo, o programa está funcionando corretamente.

./KBSync --config config

INFO config SourceType=DingDingV2, SinkType=RagFlowV2
INFO config whiteList=, blackList=
INFO config ragflowUrl=http:///XX.XX.XX.XX, ragflowApiKey=Bearer ragflow-RhMjc0NjFhNTZmNTExZjBiYWY****
INFO config ragflowDatasetId=b2af7c4c56f511f0a3d700163e****
INFO config dingDingClientId=ding9nyefxviedv****, dingDingClientSecret=Kh3qQZafV9vZZIwvP****-V7f3tkmYmcYibwT7zWNXrvOm4UbETOhqEt****
INFO config dingDingUserId=012713339****
NFO Verifying RAGFlow connection...
INFO Attempting to list datasets to validate the connection...
INFO Successfully found matching dataset: Name='test', ID='b2af7c4c56f511f0a3d700163e****'
INFO RAGFlow connection verified successfully.
INFO Starting DingTalk authentication process...
INFO Waiting for the initial app access token...
INFO App access token refresh loop started.
INFO Attempting to refresh the app access token...
INFO {'headers': {'server': 'DingTalk/1.0.0', 'date': 'Tue, 29 Jul 2025 09:14:19 GMT', 'content-type': 'application/json;charset=utf-8', 'transfer-encoding': 'chunked', 'connection': 'keep-alive', 'access-control-allow-origin': '*', 'access-control-expose-headers': '*', 'x-acs-request-id': 'AD15D9B5-C47D-7C06-BCE7-03AA76A****', 'x-acs-trace-id': 'ad2c67867d7153507b9a74e399****', 'access-control-allow-headers': 'X-Requested-With, X-Sequence, _aop_secret, _aop_signature, x-acs-dingtalk-access-token', 'content-encoding': 'gzip'}, 'statusCode': 200, 'body': {'accessToken': '38a7d120903c35a7aa2e866dca****', 'expireIn': 7200}}
INFO set dingding access token: 38a7d120903c35a7aa2e866dca****
INFO set dingding access token expires in: 7200
INFO App access token refreshed successfully. Next refresh scheduled in 6600 seconds.
INFO Waiting 6600 seconds until the next token refresh.
INFO Initial app access token acquired.
INFO Fetching user UnionID...
INFO set dingding union id: XYesTh9u****
INFO Successfully fetched UnionID.

Apêndice

Obter a URL do servidor de API

Faça login na página do RAGFlow.
No painel de navegação à esquerda, clique em API.
Obtenha o servidor de API.

Obter a chave de API

Faça login na página do RAGFlow.
No painel de navegação à esquerda, clique em API.
À direita de RAGFlow API, clique em API KEY.
Na caixa de diálogo API KEY, clique em Create New Key.
Clique em para copiar a chave e salve-a em um local seguro.

Obter o ID da base de conhecimento

Faça login na página do RAGFlow.
Na página Knowledge Base, clique na base de conhecimento desejada.
Na URL da barra de endereços do navegador, copie o ID da base de conhecimento.

Nota
O ID da base de conhecimento corresponde à sequência de caracteres após id=.