KnowledgeSDK是一个Go语言库，用于构建和管理基于向量的知识库，提供语义搜索功能。它提供了一套完整的工具，用于文档管理、分块、嵌入向量生成和语义搜索。
- 知识库管理（创建、读取、更新、删除）
- 自动内容提取的文档处理
- 高效存储和检索的文本分块
- 向量嵌入生成
- 带相似度评分的语义搜索
- 基于PostgreSQL的向量存储和高效索引
- 通过Apache Tika集成支持各种文件格式
- 符合Dify规范的External Knowledge API服务
type Config struct {
// 数据库配置
DBHost string
DBPort int
DBName string
DBUser string
DBPassword string
// 向量嵌入服务配置
APIKey string
BaseURL string // 兼容不同的模型服务
EmbeddingModel string // 如"text-embedding-ada-002"
}type ChunkConfig struct {
ChunkSize int // 每个块的最大字符数
Overlap int // 相邻块之间的重叠字符数
}type SearchParams struct {
Query string // 要搜索的查询文本
TopK int // 返回结果的数量
SimilarityThreshold float64 // 最小相似度分数（0-1）
CreatorID string // 创建者ID，用于过滤搜索结果（可选）
KBID string // 知识库ID，用于限制搜索范围（可选）
}type TikaConfig struct {
URL string // Tika服务器URL，例如"http://localhost:9998"
}
// DefaultTikaConfig 返回默认的Tika配置，URL设置为"http://localhost:9998"创建一个新的SDK实例，使用提供的配置。
- 参数:
config Config: 数据库和嵌入服务的配置
- 返回:
*KnowledgeSDK: SDK实例error: 初始化失败时的错误
创建一个新的知识库。
- 参数:
ctx context.Context: 操作上下文kb *KnowledgeBase: 知识库对象，包含以下字段：Name: 知识库名称Description: 知识库描述ModelID: 大模型的唯一标识符（可选）Temperature: 模型温度参数，控制输出的随机性（可选，默认0.7）RigorousPrompt: 严谨回答的提示词（可选）EnableRigorousAnswer: 是否启用严谨回答模式（可选，默认false）ChunkSize: 文档分块大小（可选，默认1000）Overlap: 相邻分块的重叠字符数（可选，默认50）TopK: 知识检索返回的最大相关片段数量（可选，默认5）SimilarityThreshold: 相似度阈值（可选，默认0.6）SystemPromptTemplate: 系统提示词模板（可选）MaxReferenceLength: 参考知识最大字符数（可选，默认3000）CreatorID: 知识库创建者的ID（可选）
- 返回:
*KnowledgeBase: 创建的知识库error: 创建失败时的错误
通过ID检索知识库。
- 参数:
ctx context.Context: 操作的上下文kbID string: 知识库ID
- 返回:
*KnowledgeBase: 检索的知识库error: 检索失败时的错误
列出所有知识库。
- 参数:
ctx context.Context: 操作的上下文
- 返回:
[]KnowledgeBase: 知识库列表error: 列表失败时的错误
根据创建者ID列出知识库。
- 参数:
ctx context.Context: 操作的上下文creatorID string: 创建者ID
- 返回:
[]KnowledgeBase: 知识库列表error: 列表失败时的错误
根据知识库ID列表检索多个知识库。
- 参数:
ctx context.Context: 操作的上下文kbIDs []string: 知识库ID列表
- 返回:
[]KnowledgeBase: 知识库列表error: 检索失败时的错误
更新知识库的所有属性。
- 参数:
ctx context.Context: 操作上下文kb *KnowledgeBase: 包含更新字段的知识库对象Name: 知识库名称Description: 知识库描述ModelID: 大模型的唯一标识符（可选）Temperature: 模型温度参数，控制输出的随机性（可选，默认0.7）RigorousPrompt: 严谨回答的提示词（可选）EnableRigorousAnswer: 是否启用严谨回答模式（可选，默认false）TopK: 知识检索返回的最大相关片段数量（可选，默认5）SimilarityThreshold: 相似度阈值（可选，默认0.6）SystemPromptTemplate: 系统提示词模板（可选）MaxReferenceLength: 参考知识最大字符数（可选，默认3000）
- 返回:
*KnowledgeBase: 更新后的知识库error: 更新失败时的错误
删除知识库及其所有文档。
- 参数:
ctx context.Context: 操作的上下文kbID string: 知识库ID
- 返回:
error: 删除失败时的错误
列出知识库中的所有文档。
- 参数:
ctx context.Context: 操作的上下文kbID string: 知识库ID
- 返回:
[]Document: 文档列表error: 列表失败时的错误
分页列出知识库中的文档，支持排序和文件名关键字模糊匹配。
- 参数:
ctx context.Context: 操作的上下文kbID string: 知识库IDkeyword string: 用于过滤文档名称的关键字（空字符串表示不过滤）page int: 页码（从1开始）pageSize int: 每页文档数orderBy string: 排序标准（如"uploaded_at DESC"）creatorID string: 创建者ID（可选，用于过滤）
- 返回:
[]Document: 文档列表int64: 符合过滤条件的知识库文档总数error: 列表失败时的错误
向知识库添加文本文档并立即分块。
- 参数:
ctx context.Context: 操作的上下文kbID string: 知识库IDname string: 文档名称content string: 文档内容chunkConfig ChunkConfig: 分块配置
- 返回:
*Document: 添加的文档error: 添加失败时的错误
向知识库添加带元数据的文档并分块。
- 参数:
ctx context.Context: 操作的上下文kbID string: 知识库IDname string: 文档名称content string: 文档内容contentType string: 内容MIME类型metadata map[string]string: 文档元数据chunkConfig ChunkConfig: 分块配置
- 返回:
*Document: 添加的文档error: 添加失败时的错误
通过ID检索文档。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
*Document: 检索的文档error: 检索失败时的错误
检索文档及其分块。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
*Document: 检索的带分块的文档error: 检索失败时的错误
删除文档及其分块。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
error: 删除失败时的错误
更新文档内容并重新分块。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档IDnewContent string: 新文档内容chunkConfig ChunkConfig: 分块配置
- 返回:
error: 更新失败时的错误
检索文档的元数据。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
map[string]string: 文档元数据error: 检索失败时的错误
向知识库添加文件，提取其内容并分块。
- 参数:
ctx context.Context: 操作的上下文kbID string: 知识库IDfileName string: 文件名fileData []byte: 文件数据tikaConfig TikaConfig: Apache Tika配置chunkConfig ChunkConfig: 分块配置
- 返回:
*Document: 添加的文档error: 添加失败时的错误
从io.Reader向知识库添加文件。
- 参数:
ctx context.Context: 操作的上下文kbID string: 知识库IDfileName string: 文件名reader io.Reader: 文件数据读取器tikaConfig TikaConfig: Apache Tika配置chunkConfig ChunkConfig: 分块配置
- 返回:
*Document: 添加的文档error: 添加失败时的错误
从HTTP多部分上传向知识库添加文件。
- 参数:
ctx context.Context: 操作的上下文kbID string: 知识库IDfile *multipart.FileHeader: 上传的文件tikaConfig TikaConfig: Apache Tika配置chunkConfig ChunkConfig: 分块配置
- 返回:
*Document: 添加的文档error: 添加失败时的错误
从文件中提取内容和元数据，使用Apache Tika。
- 参数:
ctx context.Context: 操作的上下文fileName string: 文件名fileData []byte: 文件数据tikaConfig TikaConfig: Apache Tika配置
- 返回:
*FileContent: 提取的内容和元数据error: 提取失败时的错误
从io.Reader中提取文件内容和元数据。
- 参数:
ctx context.Context: 操作的上下文fileName string: 文件名reader io.Reader: 文件数据读取器tikaConfig TikaConfig: Apache Tika配置
- 返回:
*FileContent: 提取的内容和元数据error: 提取失败时的错误
从HTTP多部分上传的文件中提取内容和元数据。
- 参数:
ctx context.Context: 操作的上下文file *multipart.FileHeader: 上传的文件tikaConfig TikaConfig: Apache Tika配置
- 返回:
*FileContent: 提取的内容和元数据error: 提取失败时的错误
从指定URL的文件中提取内容和元数据。
- 参数:
ctx context.Context: 操作的上下文fileURL string: 文件的URLtikaConfig TikaConfig: Apache Tika配置
- 返回:
*FileContent: 提取的内容和元数据error: 提取失败时的错误
提取文件的元数据，但不存储该文件。
- 参数:
ctx context.Context: 操作的上下文fileName string: 文件名fileData []byte: 文件数据tikaConfig TikaConfig: Apache Tika配置
- 返回:
map[string]string: 文件元数据error: 提取失败时的错误
从io.Reader中提取文件的元数据，但不存储该文件。
- 参数:
ctx context.Context: 操作的上下文fileName string: 文件名reader io.Reader: 文件数据读取器tikaConfig TikaConfig: Apache Tika配置
- 返回:
map[string]string: 文件元数据error: 提取失败时的错误
从HTTP多部分上传的文件中提取元数据，但不存储该文件。
- 参数:
ctx context.Context: 操作的上下文file *multipart.FileHeader: 上传的文件tikaConfig TikaConfig: Apache Tika配置
- 返回:
map[string]string: 文件元数据error: 提取失败时的错误
执行向量相似度搜索。
- 参数:
ctx context.Context: 操作的上下文params SearchParams: 搜索参数，包括：Query: 要搜索的查询文本TopK: 返回结果的最大数量SimilarityThreshold: 最小相似度分数（0-1）CreatorID: 创建者ID，用于过滤结果（可选）KBID: 知识库ID，用于限制搜索范围（可选）
- 返回:
[]SearchResult: 搜索结果error: 搜索失败时的错误
执行传统的全文搜索。
- 参数:
ctx context.Context: 操作的上下文query string: 搜索查询limit int: 最大结果数creatorID string: 创建者ID，用于过滤结果（可选）kbID string: 知识库ID，用于限制搜索范围（可选）
- 返回:
[]SearchResult: 搜索结果error: 搜索失败时的错误
执行混合搜索（向量 + 全文）。
- 参数:
ctx context.Context: 操作的上下文params SearchParams: 搜索参数，包括：Query: 要搜索的查询文本TopK: 返回结果的最大数量SimilarityThreshold: 最小相似度分数（0-1）CreatorID: 创建者ID，用于过滤结果（可选）KBID: 知识库ID，用于限制搜索范围（可选）
- 返回:
[]SearchResult: 搜索结果error: 搜索失败时的错误
为文本生成向量嵌入。
- 参数:
ctx context.Context: 操作的上下文text string: 要嵌入的文本
- 返回:
[]float32: 向量嵌入error: 生成失败时的错误
批量为多个文本生成向量嵌入。
- 参数:
ctx context.Context: 操作的上下文texts []string: 要嵌入的文本
- 返回:
[][]float32: 向量嵌入error: 生成失败时的错误
检索嵌入向量生成的状态。
- 参数:
ctx context.Context: 操作的上下文
- 返回:
*ChunkStatus: 状态信息error: 检索失败时的错误
更新分块的向量嵌入。
- 参数:
ctx context.Context: 操作的上下文chunk *Chunk: 要更新的分块embedding []float32: 向量嵌入
- 返回:
error: 更新失败时的错误
批量更新多个分块的向量嵌入。
- 参数:
ctx context.Context: 操作的上下文chunks []Chunk: 要更新的分块embeddings [][]float32: 向量嵌入
- 返回:
error: 更新失败时的错误
检索待处理嵌入生成的分块。
- 参数:
ctx context.Context: 操作的上下文limit int: 最大分块数
- 返回:
[]Chunk: 待处理的分块error: 检索失败时的错误
更新文档状态。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档IDstatus string: 新状态
- 返回:
error: 更新失败时的错误
标记文档上传成功。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
error: 标记失败时的错误
标记文档上传失败。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
error: 标记失败时的错误
标记文档内容提取成功。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
error: 标记失败时的错误
标记文档内容提取失败。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
error: 标记失败时的错误
标记文档分块成功。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
error: 标记失败时的错误
标记文档分块失败。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
error: 标记失败时的错误
标记文档索引成功。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
error: 标记失败时的错误
标记文档索引失败。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
error: 标记失败时的错误
检查文档是否准备好进行内容提取。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
bool: 如果准备好返回true，否则返回falseerror: 检查失败时的错误
检查文档是否准备好进行分块。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
bool: 如果准备好返回true，否则返回falseerror: 检查失败时的错误
检查文档是否准备好进行索引。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
bool: 如果准备好返回true，否则返回falseerror: 检查失败时的错误
检索具有特定状态的文档。
- 参数:
ctx context.Context: 操作的上下文status string: 过滤状态limit int: 最大文档数
- 返回:
[]Document: 具有指定状态的文档error: 检索失败时的错误
检索等待内容提取的文档。
- 参数:
ctx context.Context: 操作的上下文limit int: 最大文档数
- 返回:
[]Document: 等待内容提取的文档error: 检索失败时的错误
检索等待分块的文档。
- 参数:
ctx context.Context: 操作的上下文limit int: 最大文档数
- 返回:
[]Document: 等待分块的文档error: 检索失败时的错误
检索等待索引的文档。
- 参数:
ctx context.Context: 操作的上下文limit int: 最大文档数
- 返回:
[]Document: 等待索引的文档error: 检索失败时的错误
检查文档的所有分块是否都已索引。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
bool: 如果所有分块都已索引返回true，否则返回falseerror: 检查失败时的错误
基于分块更新文档的索引状态。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档ID
- 返回:
error: 更新失败时的错误
更新多个文档分块。
- 参数:
ctx context.Context: 操作的上下文chunks []Chunk: 要更新的分块
- 返回:
error: 更新失败时的错误
检索需要索引的分块。
- 参数:
ctx context.Context: 操作的上下文limit int: 最大分块数
- 返回:
[]Chunk: 需要索引的分块error: 检索失败时的错误
标记分块为已索引。
- 参数:
ctx context.Context: 操作的上下文docID string: 文档IDchunkIndex int: 分块索引
- 返回:
error: 标记失败时的错误
比较两个分块的内容。
- 参数:
chunk1 *Chunk: 第一个分块chunk2 *Chunk: 第二个分块
- 返回:
bool: 如果内容相同返回true，否则返回false
检索GORM数据库连接。
- 返回:
*gorm.DB: 数据库连接
检索OpenAI客户端。
- 返回:
*openai.Client: OpenAI客户端
检索当前使用的嵌入模型名称。
- 返回:
string: 嵌入模型名称
检索模型向量维度。
- 返回:
int: 向量维度
将向量嵌入转换为PostgreSQL向量格式。
- 参数:
embedding []float32: 向量嵌入
- 返回:
string: PostgreSQL向量格式
返回默认的Tika配置。
- 返回:
TikaConfig: 默认的Tika配置，URL设置为"http://localhost:9998"
DocStatusUploadFailed: 上传失败DocStatusUploadSuccess: 上传成功，等待内容提取DocStatusExtractFailed: 内容提取失败DocStatusExtractSuccess: 内容提取成功，等待分块DocStatusSplitFailed: 分块失败DocStatusSplitSuccess: 分块成功，等待索引DocStatusIndexFailed: 索引失败DocStatusIndexSuccess: 索引成功
KnowledgeSDK 提供了一个符合 Dify External Knowledge API 规范 的服务实现，可以将你的知识库系统连接到 Dify 平台。
- 运行服务
# 使用默认配置
make run-external
# 或者使用自定义参数
./cmd/external-knowledge-api/main.go --config config.yaml --api-key your-api-key --port 8080- 在 Dify 中配置
在 Dify 中创建知识库时：
- 选择 "External Knowledge API" 类型
- 填入 API 端点：
http://your-server:8080/retrieval - 填入 API 密钥
检索知识库内容。
请求示例：
{
"knowledge_id": "your-knowledge-id",
"query": "搜索内容",
"retrieval_setting": {
"top_k": 5,
"score_threshold": 0.5
},
"metadata_condition": {
"logical_operator": "and",
"conditions": [
{
"name": ["category"],
"comparison_operator": "contains",
"value": "tutorial"
}
]
}
}响应示例：
{
"records": [
{
"content": "内容片段",
"score": 0.95,
"title": "文档标题",
"metadata": {
"path": "文档路径",
"description": "文档描述"
}
}
]
}- ✅ 完全兼容 Dify 规范
- ✅ 支持元数据过滤
- ✅ Bearer Token 认证
- ✅ 支持所有比较操作符
- ✅ 健康检查端点
- ✅ 详细的错误码
详细文档请参考 External Knowledge API 文档。