Transferir dados do Lark 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.

Informações gerais

Tipos de dados compatíveis

O RAGFlow do DTS aceita dados do Lark Docs, Sheets, Bitable e Wiki.

Métodos de acesso

Acesse os dados do Lark com um token de acesso de aplicativo (tenant_access_token) ou um token de acesso de usuário (user_access_token).

Método	Tipo de permissão	Vantagens	Desvantagens
`tenant_access_token` (Recomendado)	Identidade do aplicativo	Compatível com transferência retomável. Exige configuração única para transferir uma pasta ou Wiki individual.	Autorização mais complexa. Configure permissões de acesso separadas para Drive e Wiki.
`user_access_token`	Identidade do usuário	Autorização simplificada. Concede acesso a todas as pastas sem exigir permissões distintas para Drive e Wiki.	Obtenha um novo código de autorização do Lark sempre que executar o programa KBSync. O código de autorização do Lark expira.

Antes de começar

Faça login na Plataforma Aberta do Lark e acesse o Developer Console.
Crie um aplicativo.

Clique em Create Enterprise-developed Application, configure informações como Name e Application Description e clique em Create.
Clique no cartão do aplicativo para abrir a página de configuração.

Por padrão, você estará na página Basic Information > Credentials and Basic Information.
Na página Credentials and Basic Information, seção Application Credentials, anote o App ID e o App Secret.

Procedimento

Nota

Para instruções detalhadas sobre o Lark, consulte a documentação oficial (Central de Ajuda e documentos de desenvolvimento).

Etapa 1: Configurar permissões de acesso

Token de acesso de aplicativo

Faça login na Plataforma Aberta do Lark e acesse o Developer Console.
Clique no aplicativo criado na seção Antes de começar.
Adicione um bot e publique o aplicativo.
1. No painel de navegação à esquerda, selecione Application Capabilities > Add Application Capability.
2. Na aba Add by Capability, no cartão do bot, clique em Add.
3. No topo da página, clique em Create Version.
  
  Nota
  Alternativamente, no painel de navegação à esquerda, selecione App Publishing > Version Management and Publishing e clique em Create Version.
4. Na página Version Details, insira a Application Version e a Update Description.
  
  Nota
  Use o bot padrão para as default mobile client capabilities e default desktop client capabilities.
5. Clique em Save.
6. Na caixa de diálogo exibida, clique em Confirm Publish.
Configure as permissões de API.
1. No painel de navegação à esquerda, selecione Development Configuration > Permission Management.
2. Clique em Batch Import/Export Permissions.
3. Na aba Import, caixa de texto JSON, configure as seguintes permissões de identidade de usuário para o aplicativo.
```
{
  "scopes": {
    "tenant": [
      "docs:document:export",
      "drive:drive",
      "wiki:wiki"
    ],
    "user": []
  }
}
```
4. Clique em Next to confirm the new permissions.
5. Clique em Activate Now.
Faça login no cliente Lark, crie um grupo e adicione o aplicativo criado na seção Antes de começar como group bot.
Configure as permissões de acesso para Drive e Wiki.
Permissões do Drive
1. Acesse a pasta de destino no Drive.
2. No lado direito da página, clique em Share.
3. Em Invite collaborators, adicione o grupo criado na Etapa 5.
  
  A permissão padrão Read é suficiente.
4. Clique em Send.
Permissões da Wiki
1. Acesse a página All Wikis.
2. Passe o ponteiro sobre a base de conhecimento desejada e clique em Knowledge Base Settings.
3. Clique na aba Member Settings. Na área Roles and Permissions, aba Administrator, clique em Add Administrator.
4. Na caixa de diálogo exibida, adicione o grupo criado na Etapa 5 e clique em Next.
5. Clique em Send.

Token de acesso de usuário

Faça login na Plataforma Aberta do Lark e acesse o Developer Console.
Clique no aplicativo criado na seção Antes de começar.
Configure as permissões de API.
1. No painel de navegação à esquerda, selecione Development Configuration > Permission Management.
2. Clique em Batch Import/Export Permissions.
3. Cole o JSON abaixo para conceder as permissões de identidade de usuário necessárias ao aplicativo criado.
```
{
  "scopes": {
    "tenant": [],
    "user": [
      "offline_access",
      "docs:document:export",
      "drive:drive",
      "wiki:wiki"
    ]
  }
}
```
4. Clique em Next, Confirm New Permissions.
5. Clique em Activate Now.
Configure a URL de redirecionamento.
1. No painel de navegação à esquerda, selecione Development Configuration > Security Settings.
2. Na caixa de texto Redirect URL, insira https://www.aliyun.com.
3. Clique em Add à direita da caixa de texto.
4. Ative a opção Refresh user_access_token.
  
  Nota
  Se essa opção não estiver visível, o recurso já está habilitado por padrão.
Obtenha o código de autorização.
1. Monte a URL da página de autorização do Lark.
  
  Nota
  Substitua YOUR_FEISHU_CLIENT_ID na URL pelo App ID anotado na seção Antes de começar.
```
https://accounts.feishu.cn/open-apis/authen/v1/authorize?client_id=YOUR_FEISHU_CLIENT_ID&redirect_uri=https://www.aliyun.com&scope=drive:drive offline_access docs:document:export wiki:wiki
```
2. Abra a página de autorização no navegador.
3. Clique em Authorize.
4. Extraia o código de autorização (code) da URL de redirecionamento.
  
  Nota
  O código de autorização não inclui code=, & nem quaisquer informações após o símbolo &.

Etapa 2: Obter o token da pasta do Lark e o ID da Wiki

Faça login no cliente Lark.
Obtenha o token da pasta do Lark Docs.
1. Acesse a pasta de destino.
2. Copie a URL da pasta na barra de endereços do navegador.
3. Extraia o token da URL (parte após folder/).
  
  Nota
  O token não inclui o caractere ? nem qualquer informação subsequente.
Obtenha o ID da Wiki.
1. Acesse a página All Wikis.
2. Passe o ponteiro sobre a base de conhecimento desejada e clique em Knowledge Base Settings.
3. Copie a URL da Wiki de destino na barra de endereços do navegador.
4. Extraia o ID da base de conhecimento da URL (sequência após settings/).
  
  Nota
  O ID da base de conhecimento é puramente numérico e não inclui o símbolo # nem informações posteriores.

Etapa 3: Executar o programa KBSync

Obtenha o arquivo KBSync.

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

Nota
O programa KBSync requer um ambiente Linux com acesso à Plataforma Aberta do Lark e ao RAGFlow.

Prepare o arquivo config.

Crie um arquivo chamado config no sistema Linux.

Copie o código abaixo para o arquivo config.

whiteList=
blackList=
sinkType=RagFlow
sourceType=FeiShu
ragflowUrl=http://XX.XX.XX.XX
ragflowApiKey=Bearer RAGFlow-BmND******MDI0Mm
ragflowDatasetId=928d061******2ac120006
feishuAppId=cli_a8a******d00d
feishuAppSecret=pMp73Si******UDrWXBSOa
feishuUserAccessCode=bGzpx6******B9KFCdzdCDHG
feishuCloudSpaceDirToken=ESJm*******CRdn002cii3bnAc
feishuWikiSpaceId=7504968******8674

Substitua os parâmetros no arquivo config.

Importante

Deixe o valor vazio para parâmetros que não precisam de configuração.
Se forem fornecidos valores tanto para feishuCloudSpaceDirToken quanto para feishuWikiSpaceId, apenas o Lark Docs e suas pastas pai serão transferidos, pois somente o parâmetro feishuCloudSpaceDirToken terá efeito.
O parâmetro blackList tem prioridade sobre o parâmetro whiteList.

Parâmetro	Obrigatório	Descrição	Como obter
`whiteList`	Não	Caminhos dos arquivos a transferir (lista de permissões) e dos arquivos a excluir (lista de bloqueios). Incluem caminhos de pastas no Lark Docs e caminhos de documentos na base de conhecimento. Nota Compatível com expressões regulares. Separe múltiplos caminhos com espaços.	Obtenha os caminhos no cliente Lark.
`blackList`	Não		Obtenha os caminhos no cliente Lark.
`sinkType`	Sim	Tipo do destino.	Defina este parâmetro como `RagFlow`.
`sourceType`	Sim	Tipo da origem.	Defina este parâmetro como `Feishu`.
`ragflowUrl`	Sim	Endereço do RAGFlow (API server).	Obter o endereço do API server do RAGFlow.
`ragflowApiKey`	Sim	Chave de API da base de conhecimento RAGFlow.	Obter a chave de API do RAGFlow.
`ragflowDatasetId`	Sim	ID da base de conhecimento RAGFlow.	Obter o ID da base de conhecimento RAGFlow.
`feishuAppId`	Sim	ID do aplicativo no Lark (App ID).	Obter o App ID e o App Secret.
`feishuAppSecret`	Sim	Segredo do aplicativo no Lark (App Secret).	Obter o App ID e o App Secret.
`feishuUserAccessCode`	Não Nota Este parâmetro é necessário apenas ao acessar dados do Lark pelo método user_access_token.	Código de autorização do Lark.	Obter o código de autorização.
`feishuCloudSpaceDirToken`	Não Nota Forneça valor para apenas um destes parâmetros.	Token da pasta que contém o Lark Docs.	Obter o token da pasta do Lark Docs e o ID da base de conhecimento.
`feishuWikiSpaceId`		ID da base de conhecimento do Lark.

Coloque o arquivo KBSync e o arquivo de configuração config no mesmo diretório em um ambiente Linux.

No ambiente Linux, execute o comando ./KBSync --config config para iniciar o programa KBSync.

A saída abaixo indica que o KBSync está funcionando corretamente.

./KBSync --config config

INFO config whiteList=, blackList=
INFO config ragflowUrl=http://XX.XX.XX.XX/, ragflowApiKey=Bearer RAGFlow-BmND******MDI0Mm
INFO config ragflowDatasetId=928d061******2ac120006
INFO config feishuAppId=cli_a8a******d00d, feishuAppSecret=pMp73Si******UDrWXBSOa
INFO Response from https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal: 200, headers: {'Server': 'Tengine', 'Content-Type': 'application/json', 'Content-Length': '102', 'Connection': 'keep-alive', 'Date': 'Tue, 08 Jul 2025 02:49:01 GMT', 'Request-Id': '25bf****-d386-4a86-****-f440f070****', 'Tt_st****': '1', 'X-Lgw-Dst-Svc': 'jbpiSR****OiA0J3d****-Oz0xugYAH9otZIFg4x****', 'X-Request-Id': '25bf****-d386-4a86-b9f4-f440f070****', 'X-Tt-Logid': '202507081049012933B870245850D****', 'server-timing': 'inner; dur=73, cdn-cache;desc=MISS,edge;dur=0,origin;dur=129', 'x-tt-trace-host': '****', 'x-tt-trace-tag': '****', 'x-tt-trace-id': '00-****', 'X-Timestamp': '175194****.952', 'Via': 'cache8.cn6540[129,0]', 'Timing-Allow-Origin': '*', 'EagleId': '6ae3651c1751942941849****'}, body: b'{"code":0,"expire":4340,"msg":"ok","tenant_access_token":"t-g10478a*******CSC3YVY"}'
INFO set feishu tenant access token expires in: 4340

Apêndice

Obter o endereço do API server do RAGFlow

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

Obter a chave de API do RAGFlow

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 RAGFlow

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

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