Skip to content

docs: rewrite external knowledge base documentation#737

Merged
RiskeyL merged 18 commits intomainfrom
docs/external-knowledge-base
Apr 15, 2026
Merged

docs: rewrite external knowledge base documentation#737
RiskeyL merged 18 commits intomainfrom
docs/external-knowledge-base

Conversation

@RiskeyL
Copy link
Copy Markdown
Contributor

@RiskeyL RiskeyL commented Apr 9, 2026

Summary

  • Rewrote the external knowledge base overview page with a clear three-step flow (build API → register in Dify → connect knowledge source), verified troubleshooting, and removed inaccurate content
  • Rewrote the External Knowledge API specification with correct request/response contracts verified against the codebase—fixed field types, added missing comparison operators, clarified error handling behavior
  • Standardized "similarity score" terminology across all docs and API references, replacing inconsistent "relevance score" usage to match the product UI
  • Added "similarity score", "External Knowledge ID", and adjustable parameter guidance to the glossary and style guide

Changed Files

File Change
en/use-dify/knowledge/connect-external-knowledge-base.mdx Full rewrite
en/use-dify/knowledge/external-knowledge-api.mdx Full rewrite
en/use-dify/knowledge/integrate-knowledge-within-application.mdx Terminology fix
en/api-reference/openapi_*.json (4 files) Terminology fix
writing-guides/glossary.md Added entries
writing-guides/style-guide.md Added pattern
images/connect-to-external-knowledge-base.png New screenshot

Copilot AI review requested due to automatic review settings April 9, 2026 12:01
@mintlify
Copy link
Copy Markdown
Contributor

mintlify bot commented Apr 9, 2026 •
edited
Loading

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
dify-core-product 🟢 Ready View Preview Apr 9, 2026, 12:05 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@dosubot dosubot bot added the size:L This PR changes 100-499 lines, ignoring generated files. label Apr 9, 2026
@dosubot dosubot bot added the documentation Improvements or additions to documentation label Apr 9, 2026
Copilot AI reviewed Apr 9, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR rewrites and standardizes the documentation for integrating External Knowledge Bases with Dify, aligning terminology and API contracts across user docs, writing guides, and OpenAPI references.

Changes:

  • Rewrites the external knowledge base overview and the External Knowledge API specification to reflect a clearer integration flow and updated request/response guidance.
  • Standardizes terminology from “relevance score” to “similarity score” across docs and API references.
  • Updates the glossary/style guide with new terminology and guidance; adds a new UI screenshot for the connection flow.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
writing-guides/style-guide.md Adds guidance for documenting adjustable/tunable parameters via tradeoffs.
writing-guides/glossary.md Adds/updates glossary entries for “similarity score” and “External Knowledge ID”.
images/connect-to-external-knowledge-base.png Adds a new screenshot used in the external knowledge connection docs.
en/use-dify/knowledge/integrate-knowledge-within-application.mdx Updates rerank terminology to “similarity score”.
en/use-dify/knowledge/external-knowledge-api.mdx Full rewrite of the API contract: auth, request/response schema, metadata filtering, and error handling.
en/use-dify/knowledge/connect-external-knowledge-base.mdx Full rewrite of the overview page with a 3-step flow + troubleshooting section.
en/api-reference/openapi_knowledge.json Updates score/threshold descriptions to “similarity score”.
en/api-reference/openapi_completion.json Updates score description to “similarity score”.
en/api-reference/openapi_chatflow.json Updates score description to “similarity score”.
en/api-reference/openapi_chat.json Updates score description to “similarity score”.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

github-actions bot added a commit that referenced this pull request Apr 9, 2026
@github-actions
🌐 Initial translations for PR #737
06203db 
Auto-generated translations for documentation changes in PR #737.

Last-Processed-Commit: 7ac0849
Original-PR: #737
Languages: Chinese (zh), Japanese (ja)

🤖 Generated with GitHub Actions
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 9, 2026

🌐 Multi-language Sync

✅ Created sync PR #738

Synced 13 files to cn + jp

⚠️ 1 file failed:

  • zh/use-dify/knowledge/external-knowledge-api.mdx

Both PRs can merge independently. Future commits here will auto-update the sync PR.

@github-actions github-actions bot mentioned this pull request Apr 9, 2026
Closed
github-actions bot added a commit that referenced this pull request Apr 10, 2026
@github-actions
🔄 Update translations for commit a047f7b
64703a6 
Auto-generated translations for changes in commit a047f7b.

Last-Processed-Commit: a047f7b
Original-PR: #737
Languages: Chinese (zh), Japanese (ja)

🤖 Generated with GitHub Actions
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 10, 2026

🌐 Multi-language Sync

✅ Updated sync PR #738

Synced 4 files to cn + jp

Future commits will auto-update the sync PR.

Copilot AI review requested due to automatic review settings April 10, 2026 03:45
@dosubot dosubot bot added size:XXL This PR changes 1000+ lines, ignoring generated files. and removed size:L This PR changes 100-499 lines, ignoring generated files. labels Apr 10, 2026
Copilot AI reviewed Apr 10, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 10 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings April 10, 2026 04:22
Copilot AI reviewed Apr 10, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 9 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot AI review requested due to automatic review settings April 14, 2026 12:57
Copilot AI reviewed Apr 14, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 4 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@RiskeyL RiskeyL merged commit 7cea249 into main Apr 15, 2026
2 of 3 checks passed
@RiskeyL RiskeyL deleted the docs/external-knowledge-base branch April 15, 2026 02:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation size:XXL This PR changes 1000+ lines, ignoring generated files.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@RiskeyL