Docs
Contents

External Data Sources and Yuque Documents

A data source brings external Yuque content into a knowledge base. You can configure a team data source and manage synchronization, or authorize a personal Yuque account to import online documents. Import and ingestion are separate steps: a document must finish parsing, chunking, and embedding before it can be searched.

Overview

These features depend on the target environment's Yuque configuration, outbound connectivity, user authorization, and knowledge base model configuration. Available controls and fields depend on the deployed console.

Prerequisites

  1. Create the target project and knowledge base and obtain the project permissions needed for the intended write operations.

  2. Configure an available embedding model and a parser suitable for the files. For images or scanned content, ensure a suitable vision model is available.

  3. Ensure the Yuque account can read the target documents. For a team source, prepare the connection information required by the environment. Personal imports require Yuque authorization in the console.

  4. Make sure the documents may be shared with the target knowledge base. Do not put access credentials in documentation, logs, or source control.

External data source integration and Yuque incremental sync: workflow diagram, not a runtime screenshot

Workflow diagram, not a runtime screenshot.

View the flow diagram in full size

Configure a team data source

  1. Open Data Sources in the target knowledge base, choose to create a source, enter a name, and select Yuque.

  2. Enter the team connection details and the knowledge base scope requested by the form. Select documents and configure a schedule as needed. A version draft may not offer scheduling.

  3. To synchronize immediately after creation, select the corresponding option; otherwise, start a sync from the data source list later. Creating a source and completing a sync are distinct states.

  4. Check status and synchronization records. For partial failures, inspect individual errors and resolve permissions or source issues. New or updated documents still need to finish ingestion before they can be searched.

Team connection credentials belong to the team source configuration and are not the same as a personal Yuque authorization. A working team connection does not imply that the current user's personal documents are accessible.

Import personal Yuque documents from the Documents page

  1. On the knowledge base Documents page, choose Import online documents. Enter one supported enterprise Yuque HTTPS document URL per line, up to 20 per submission; public Yuque domains are not supported.

  2. Complete Yuque authorization as prompted. If the browser blocks the authorization popup, or authorization expires or is revoked, follow the prompt to authorize again. The account must be allowed to read each document. If knowledge base versioning is enabled, first enter the draft version to update; API callers must pass its actual versionId.

  3. Check the per-item import results. Resolve each failed item. A successful import does not mean ingestion has finished.

  4. Return to the document list and wait for the documents and ingestion jobs to become ready (ready). On the Search page, ask a question the original document can answer and verify the result and source.

The import endpoint POST /v1/knowledgebases/{knowledgeBaseId}/documents/yuque uses an authorized personal Yuque session; it returns 200 for complete success and 207 if one or more items fail, including when all fail. It requires a current user session or JWT; a server-side project API key is not a substitute for personal Yuque authorization.

Personal and team data sources

A personal source uses the current user's Yuque authorization; a team source uses the team's connection settings. Their credentials and accessible content differ: a working team connection does not mean the current user has authorized a personal source. The environment must have Yuque authorization configured before first use; contact the environment administrator if the authorization entry is unavailable.

Synchronization status describes the sync job; it does not by itself prove every document is searchable. Check ingestion status as well, and follow the relevant index page to determine whether derived indexes need rebuilding. Keep the original in Yuque as the authoritative content and update the knowledge base by syncing, so independent edits do not diverge.

Troubleshooting