WeKnora API完全手册:掌握语义检索与智能问答的调用技巧
在当今信息爆炸的时代,企业和开发者面临着如何高效处理海量文档、实现精准信息检索以及构建智能问答系统的挑战。传统的关键词匹配方式已无法满足深度语义理解的需求,而基于大语言模型(LLM)的检索增强生成(RAG)技术为解决这一痛点提供了新的范式。WeKnora作为一款功能强大的LLM框架,通过API接口将复杂的语义检索与智能问答能力开放给开发者,帮助用户轻松构建上下文感知的智能应用。
本文将从API基础、核心功能调用、实战案例到高级技巧,全面介绍WeKnora API的使用方法,助力开发者快速掌握语义检索与智能问答的调用技巧,让你的应用具备强大的文档理解和智能交互能力。
API基础:快速上手WeKnora接口
WeKnora API采用RESTful设计风格,提供了一套完整的接口用于管理租户、知识库、知识内容、模型、会话等资源,以及执行语义检索和智能问答等核心功能。在开始调用API之前,我们需要先了解API的基础信息和认证机制。
基础信息与认证
WeKnora API的基础URL为/api/v1,所有API请求都需要在此基础上构建。API支持JSON格式的请求和响应,便于数据的解析和处理。
认证方面,WeKnora采用API Key的方式进行身份验证。所有API请求都需要在HTTP请求头中包含X-API-Key字段,其值为用户的API Key。例如:
X-API-Key: sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG
为了便于问题追踪和调试,建议在每个请求的HTTP头中添加X-Request-ID字段,其值为一个唯一的请求ID。
API Key可以通过创建租户时获取,具体方法将在后续的租户管理API部分介绍。请妥善保管你的API Key,避免泄露,因为它代表你的账户身份,拥有完整的API访问权限。
API概览
WeKnora API按功能可以分为以下几类:
- 租户管理:创建和管理租户账户,租户是WeKnora系统中的独立实体,用于隔离不同用户或组织的数据和资源。
- 知识库管理:创建、查询和管理知识库,知识库是存储和组织知识内容的容器。
- 知识管理:上传、检索和管理知识内容,知识内容可以是文件、URL等多种形式。
- 模型管理:配置和管理各种AI模型,包括嵌入模型、摘要模型、重排序模型等。
- 分块管理:管理知识的分块内容,分块是知识内容经过拆分后的基本单位,便于高效检索。
- 会话管理:创建和管理对话会话,会话用于维护上下文信息,支持多轮对话。
- 聊天功能:基于知识库进行问答,支持流式响应,提供流畅的交互体验。
- 消息管理:获取和管理对话消息,便于查看历史对话记录。
- 评估功能:评估模型性能,帮助用户了解和优化模型的表现。
详细的API文档可以参考docs/API.md,其中包含了每个API的详细说明、请求参数和响应示例。
错误处理
WeKnora API使用标准的HTTP状态码表示请求状态,并返回统一的错误响应格式。当请求失败时,API会返回一个JSON对象,包含success、error等字段,其中error字段包含错误代码、错误信息和错误详情。例如:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "错误信息",
"details": "错误详情"
}
}
常见的HTTP状态码包括:
- 200:请求成功
- 400:请求参数错误
- 401:未授权,API Key无效或缺失
- 403:禁止访问,没有权限执行该操作
- 404:资源不存在
- 500:服务器内部错误
在实际开发中,建议根据API返回的状态码和错误信息进行相应的错误处理,以提高应用的健壮性。
核心功能调用:从知识库创建到智能问答
WeKnora的核心功能包括知识库管理、知识内容上传、语义检索和智能问答等。下面我们将详细介绍这些核心功能的API调用方法,并结合代码示例进行说明。
租户管理:API访问的基石
租户是WeKnora系统中的基本管理单位,每个租户拥有独立的API Key、知识库、模型等资源。在使用WeKnora API之前,我们需要先创建一个租户,以获取API Key。
创建租户
创建租户的API为POST /tenants,请求参数包括租户名称、描述、业务类型以及检索引擎配置等。例如:
curl --location 'http://localhost:8080/api/v1/tenants' \
--header 'Content-Type: application/json' \
--data '{
"name": "weknora",
"description": "weknora tenants",
"business": "wechat",
"retriever_engines": {
"engines": [
{
"retriever_type": "keywords",
"retriever_engine_type": "postgres"
},
{
"retriever_type": "vector",
"retriever_engine_type": "postgres"
}
]
}
}'
成功创建租户后,API会返回租户的详细信息,包括租户ID、名称、描述、API Key等。其中,API Key是后续调用其他API的重要凭证,需要妥善保存。
{
"data": {
"id": 10000,
"name": "weknora",
"description": "weknora tenants",
"api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG",
"status": "active",
"retriever_engines": {
"engines": [
{
"retriever_engine_type": "postgres",
"retriever_type": "keywords"
},
{
"retriever_engine_type": "postgres",
"retriever_type": "vector"
}
]
},
"business": "wechat",
"storage_quota": 10737418240,
"storage_used": 0,
"created_at": "2025-08-11T20:37:28.396980093+08:00",
"updated_at": "2025-08-11T20:37:28.396980301+08:00",
"deleted_at": null
},
"success": true
}
获取租户信息
创建租户后,可以通过GET /tenants/:id API获取指定租户的信息,其中:id为租户ID。例如:
curl --location 'http://localhost:8080/api/v1/tenants/10000' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG'
响应结果包含租户的详细信息,与创建租户时返回的信息类似。
知识库管理:组织和管理你的知识
知识库是WeKnora中用于存储和组织知识内容的容器。每个知识库可以包含多个知识项,如文件、URL等,并且可以配置分块策略、嵌入模型、重排序模型等参数。
创建知识库
创建知识库的API为POST /knowledge-bases,请求参数包括知识库名称、描述、分块配置、图像处理配置、嵌入模型ID、摘要模型ID、重排序模型ID等。例如:
curl --location 'http://localhost:8080/api/v1/knowledge-bases' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--data '{
"name": "weknora",
"description": "weknora description",
"chunking_config": {
"chunk_size": 1000,
"chunk_overlap": 200,
"separators": [
"."
],
"enable_multimodal": true
},
"image_processing_config": {
"model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e"
},
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c",
"rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0",
"vlm_model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e",
"vlm_config": {
"model_name": "qwen2.5vl:3b",
"interface_type": "ollama",
"base_url": "",
"api_key": ""
}
}'
分块配置(chunking_config)用于指定如何将知识内容拆分为分块,包括分块大小(chunk_size)、分块重叠(chunk_overlap)、分隔符(separators)以及是否启用多模态(enable_multimodal)等参数。合理的分块策略可以提高检索的准确性和效率。
成功创建知识库后,API会返回知识库的详细信息,包括知识库ID、名称、描述等。
在代码中,我们可以使用WeKnora的Go客户端来创建知识库。例如:
// Create a knowledge base
kb := &KnowledgeBase{
Name: "Test Knowledge Base",
Description: "This is a test knowledge base",
ChunkingConfig: ChunkingConfig{
ChunkSize: 500,
ChunkOverlap: 50,
Separators: []string{"\n\n", "\n", ". ", "? ", "! "},
},
ImageProcessingConfig: ImageProcessingConfig{
ModelID: "image_model_id",
},
EmbeddingModelID: "embedding_model_id",
SummaryModelID: "summary_model_id",
}
createdKB, err := apiClient.CreateKnowledgeBase(context.Background(), kb)
if err != nil {
fmt.Printf("Failed to create knowledge base: %v\n", err)
return
}
fmt.Printf("Knowledge base created successfully: ID=%s, Name=%s\n", createdKB.ID, createdKB.Name)
上述代码示例来自client/example.go,展示了如何使用Go客户端创建知识库。
混合搜索知识库内容
WeKnora支持混合搜索,即结合关键词检索和向量检索的优势,提高检索的准确性和召回率。混合搜索知识库内容的API为GET /knowledge-bases/:id/hybrid-search,请求参数包括查询文本、向量阈值、关键词阈值以及匹配数量等。例如:
curl --location --request GET 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/hybrid-search' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--data '{
"query_text": "彗星",
"vector_threshold": 0.1,
"keyword_threshold": 0.1,
"match_count": 1
}'
响应结果包含匹配的知识分块列表,每个分块包含ID、内容、知识ID、分块索引、标题、得分等信息。例如:
{
"data": [
{
"id": "7d955251-3f79-4fd5-a6aa-02f81e044091",
"content": "有几位后来xxxxx",
"knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b",
"chunk_index": 3,
"knowledge_title": "彗星.txt",
"start_at": 2287,
"end_at": 2760,
"seq": 3,
"score": 0.7402352891601821,
"match_type": 2,
"sub_chunk_id": null,
"metadata": {},
"chunk_type": "text",
"parent_chunk_id": "",
"image_info": "",
"knowledge_filename": "彗星.txt",
"knowledge_source": ""
}
],
"success": true
}
WeKnora的混合搜索流程可以用下图表示:
该图展示了WeKnora从接收用户查询到返回搜索结果的整个流程,包括查询重写、关键词检索、向量检索、结果融合、重排序等步骤。
知识管理:上传和管理你的知识内容
知识管理API用于上传、查询、更新和删除知识内容。WeKnora支持从文件和URL创建知识,满足不同场景下的知识获取需求。
从文件创建知识
从文件创建知识的API为POST /knowledge-bases/:id/knowledge/file,其中:id为知识库ID。该API支持上传各种类型的文件,如文本文件、PDF文件、图片等,并会自动对文件进行解析和分块处理。例如:
curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge/file' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
--form 'file=@"/Users/xxxx/tests/彗星.txt"' \
--form 'enable_multimodel="true"'
响应结果包含知识的详细信息,如ID、标题、文件类型、大小、解析状态等。例如:
{
"data": {
"id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5",
"tenant_id": 1,
"knowledge_base_id": "kb-00000001",
"type": "file",
"title": "彗星.txt",
"description": "",
"source": "",
"parse_status": "processing",
"enable_status": "disabled",
"embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"file_name": "彗星.txt",
"file_type": "txt",
"file_size": 7710,
"file_hash": "d69476ddbba45223a5e97e786539952c",
"file_path": "data/files/1/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/1754970756171067621.txt",
"storage_size": 0,
"metadata": null,
"created_at": "2025-08-12T11:52:36.168632288+08:00",
"updated_at": "2025-08-12T11:52:36.173612121+08:00",
"processed_at": null,
"error_message": "",
"deleted_at": null
},
"success": true
}
在代码中,我们可以使用Go客户端的CreateKnowledgeFromFile方法上传文件:
// Upload knowledge file
filePath := "path/to/sample.pdf" // Sample file path
// Check if file exists before uploading
if _, err := os.Stat(filePath); os.IsNotExist(err) {
fmt.Printf("File does not exist: %s, skipping upload step\n", filePath)
} else {
// Add metadata
metadata := map[string]string{
"source": "local",
"type": "document",
}
knowledge, err := apiClient.CreateKnowledgeFromFile(context.Background(), createdKB.ID, filePath, metadata, nil)
if err != nil {
fmt.Printf("Failed to upload knowledge file: %v\n", err)
} else {
fmt.Printf("File uploaded successfully: Knowledge ID=%s, Title=%s\n", knowledge.ID, knowledge.Title)
}
}
上述代码示例来自client/example.go,展示了如何上传文件到知识库。
智能问答:与你的知识进行交互
智能问答是WeKnora的核心功能之一,它基于知识库中的内容,结合LLM的生成能力,为用户提供准确、相关的答案。WeKnora支持普通问答和流式问答两种模式,满足不同的交互需求。
创建会话
在进行智能问答之前,需要先创建一个会话。会话用于维护对话的上下文信息,支持多轮对话。创建会话的API为POST /sessions,请求参数包括知识库ID、会话策略等。例如:
// Create a session
sessionRequest := &CreateSessionRequest{
KnowledgeBaseID: createdKB.ID,
SessionStrategy: &SessionStrategy{
MaxRounds: 10,
EnableRewrite: true,
FallbackStrategy: "fixed_answer",
FallbackResponse: "Sorry, I cannot answer this question",
EmbeddingTopK: 5,
KeywordThreshold: 0.5,
VectorThreshold: 0.7,
RerankModelID: "rerank_model_id",
RerankTopK: 3,
RerankThreshold: 0.8,
SummaryModelID: "summary_model_id",
SummaryParameters: &SummaryConfig{
Temperature: 0.7,
TopP: 0.9,
MaxTokens: 100,
},
},
}
session, err := apiClient.CreateSession(context.Background(), sessionRequest)
if err != nil {
fmt.Printf("Failed to create session: %v\n", err)
return
}
fmt.Printf("Session created successfully: ID=%s\n", session.ID)
上述代码示例来自client/example.go,展示了如何创建会话。会话策略(SessionStrategy)用于配置会话的各种参数,如最大轮数、查询重写开关、 fallback策略、嵌入模型参数、重排序模型参数等。
流式问答
流式问答可以实时返回答案的生成过程,提供更流畅的交互体验。WeKnora的流式问答API为POST /sessions/:id/qa/stream,其中:id为会话ID。
使用Go客户端进行流式问答的示例代码如下:
// Perform knowledge Q&A (using streaming API)
question := "What is artificial intelligence?"
fmt.Printf("Question: %s\nAnswer: ", question)
var answer strings.Builder
var references []*SearchResult
err = apiClient.KnowledgeQAStream(context.Background(),
session.ID,
question,
func(response *StreamResponse) error {
if response.ResponseType == ResponseTypeAnswer {
answer.WriteString(response.Content)
}
if response.Done && len(response.KnowledgeReferences) > 0 {
references = response.KnowledgeReferences
}
return nil
})
if err != nil {
fmt.Printf("Q&A failed: %v\n", err)
} else {
fmt.Printf("%s\n", answer.String())
if len(references) > 0 {
fmt.Println("References:")
for i, ref := range references {
fmt.Printf("%d. %s\n", i+1, ref.Content[:min(50, len(ref.Content))]+"...")
}
}
}
上述代码示例来自client/example.go,展示了如何使用流式问答API。通过回调函数,我们可以实时获取LLM生成的答案片段,并将其拼接成完整的答案。同时,API还会返回答案的参考来源,提高答案的可信度。
智能问答的效果可以用下图表示:
该图展示了WeKnora智能问答的界面效果,包括用户的问题、系统的回答以及相关的参考来源。
实战案例:构建一个完整的智能问答应用
为了帮助开发者更好地理解和使用WeKnora API,下面我们将通过一个实战案例,展示如何构建一个完整的智能问答应用。该应用将实现从知识库创建、知识上传到智能问答的整个流程。
案例概述
本案例将构建一个基于WeKnora的智能问答应用,该应用能够:
- 创建一个租户,获取API Key。
- 创建一个知识库,配置分块策略和模型参数。
- 上传一个PDF文件作为知识内容。
- 创建一个会话,进行多轮智能问答。
- 获取会话历史消息,查看对话记录。
实现步骤
1. 创建租户
首先,使用POST /tenants API创建一个租户,获取API Key。具体代码可以参考前面的租户管理部分。
2. 创建知识库
使用POST /knowledge-bases API创建一个知识库,配置分块策略、嵌入模型、重排序模型等参数。具体代码可以参考前面的知识库管理部分。
3. 上传知识文件
使用POST /knowledge-bases/:id/knowledge/file API上传一个PDF文件到知识库。例如:
filePath := "path/to/your/document.pdf"
metadata := map[string]string{
"source": "manual",
"category": "technical",
}
knowledge, err := apiClient.CreateKnowledgeFromFile(context.Background(), createdKB.ID, filePath, metadata, nil)
if err != nil {
fmt.Printf("Failed to upload knowledge file: %v\n", err)
return
}
fmt.Printf("File uploaded successfully: Knowledge ID=%s\n", knowledge.ID)
4. 创建会话并进行问答
创建一个会话,然后使用流式问答API进行多轮对话。例如:
// Create session
session, err := apiClient.CreateSession(context.Background(), &CreateSessionRequest{
KnowledgeBaseID: createdKB.ID,
// ... other session strategy parameters
})
if err != nil {
// handle error
}
// Q&A round 1
question1 := "What is the main topic of the document?"
fmt.Printf("Q: %s\nA: ", question1)
var answer1 strings.Builder
err = apiClient.KnowledgeQAStream(context.Background(), session.ID, question1, func(resp *StreamResponse) error {
answer1.WriteString(resp.Content)
fmt.Print(resp.Content)
return nil
})
fmt.Println()
// Q&A round 2
question2 := "Can you explain the key points of section 3?"
fmt.Printf("Q: %s\nA: ", question2)
var answer2 strings.Builder
err = apiClient.KnowledgeQAStream(context.Background(), session.ID, question2, func(resp *StreamResponse) error {
answer2.WriteString(resp.Content)
fmt.Print(resp.Content)
return nil
})
fmt.Println()
5. 获取会话历史消息
使用GET /sessions/:id/messages API获取会话的历史消息,查看对话记录。例如:
messages, err := apiClient.GetRecentMessages(context.Background(), session.ID, 10)
if err != nil {
// handle error
}
fmt.Printf("Retrieved %d messages:\n", len(messages))
for _, msg := range messages {
fmt.Printf("%s: %s\n", msg.Role, msg.Content)
}
高级技巧:优化API调用性能
在实际应用中,为了提高API调用的性能和稳定性,可以采用以下高级技巧:
- 批量操作:对于需要创建多个知识库或上传多个文件的场景,可以考虑使用批量API(如果支持)或合理组织并发请求,提高处理效率。
- 缓存策略:对于频繁访问的知识库信息、模型信息等,可以在客户端进行缓存,减少API调用次数。
- 异步处理:对于文件上传、知识解析等耗时操作,可以采用异步处理的方式,避免阻塞主线程。WeKnora的API通常会返回任务ID,客户端可以通过轮询或回调的方式获取处理结果。
- 连接池:使用HTTP连接池,复用TCP连接,减少连接建立和关闭的开销。
- 错误重试:对于偶发性的网络错误或服务器错误,可以实现指数退避的重试机制,提高请求的成功率。
总结与展望
WeKnora API为开发者提供了强大的语义检索和智能问答能力,通过本文的介绍,相信你已经掌握了WeKnora API的基本使用方法和核心功能调用技巧。从租户创建、知识库管理到知识上传、智能问答,WeKnora提供了一套完整的接口,帮助你快速构建上下文感知的智能应用。
未来,WeKnora将继续优化API性能,增加更多高级功能,如多模态知识处理、个性化推荐等,为开发者提供更好的体验。如果你在使用WeKnora API的过程中遇到任何问题,可以参考官方文档docs/API.md,或查阅源代码client/获取更多示例和细节。
最后,希望本文能够帮助你更好地理解和使用WeKnora API,让你的应用具备强大的文档理解和智能交互能力。如果你觉得本文对你有帮助,欢迎点赞、收藏、关注,获取更多关于WeKnora的技术文章和最佳实践。
Kimi-K2.5Kimi K2.5 是一款开源的原生多模态智能体模型,它在 Kimi-K2-Base 的基础上,通过对约 15 万亿混合视觉和文本 tokens 进行持续预训练构建而成。该模型将视觉与语言理解、高级智能体能力、即时模式与思考模式,以及对话式与智能体范式无缝融合。Python00- QQwen3-Coder-Next2026年2月4日,正式发布的Qwen3-Coder-Next,一款专为编码智能体和本地开发场景设计的开源语言模型。Python00
xw-cli实现国产算力大模型零门槛部署,一键跑通 Qwen、GLM-4.7、Minimax-2.1、DeepSeek-OCR 等模型Go06
PaddleOCR-VL-1.5PaddleOCR-VL-1.5 是 PaddleOCR-VL 的新一代进阶模型,在 OmniDocBench v1.5 上实现了 94.5% 的全新 state-of-the-art 准确率。 为了严格评估模型在真实物理畸变下的鲁棒性——包括扫描伪影、倾斜、扭曲、屏幕拍摄和光照变化——我们提出了 Real5-OmniDocBench 基准测试集。实验结果表明,该增强模型在新构建的基准测试集上达到了 SOTA 性能。此外,我们通过整合印章识别和文本检测识别(text spotting)任务扩展了模型的能力,同时保持 0.9B 的超紧凑 VLM 规模,具备高效率特性。Python00
KuiklyUI基于KMP技术的高性能、全平台开发框架,具备统一代码库、极致易用性和动态灵活性。 Provide a high-performance, full-platform development framework with unified codebase, ultimate ease of use, and dynamic flexibility. 注意:本仓库为Github仓库镜像,PR或Issue请移步至Github发起,感谢支持!Kotlin07
VLOOKVLOOK™ 是优雅好用的 Typora/Markdown 主题包和增强插件。 VLOOK™ is an elegant and practical THEME PACKAGE × ENHANCEMENT PLUGIN for Typora/Markdown.Less00

