首页
/ WeKnora API完全手册:掌握语义检索与智能问答的调用技巧

WeKnora API完全手册:掌握语义检索与智能问答的调用技巧

2026-02-05 05:00:18作者:裴锟轩Denise

在当今信息爆炸的时代,企业和开发者面临着如何高效处理海量文档、实现精准信息检索以及构建智能问答系统的挑战。传统的关键词匹配方式已无法满足深度语义理解的需求,而基于大语言模型(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按功能可以分为以下几类:

  1. 租户管理:创建和管理租户账户,租户是WeKnora系统中的独立实体,用于隔离不同用户或组织的数据和资源。
  2. 知识库管理:创建、查询和管理知识库,知识库是存储和组织知识内容的容器。
  3. 知识管理:上传、检索和管理知识内容,知识内容可以是文件、URL等多种形式。
  4. 模型管理:配置和管理各种AI模型,包括嵌入模型、摘要模型、重排序模型等。
  5. 分块管理:管理知识的分块内容,分块是知识内容经过拆分后的基本单位,便于高效检索。
  6. 会话管理:创建和管理对话会话,会话用于维护上下文信息,支持多轮对话。
  7. 聊天功能:基于知识库进行问答,支持流式响应,提供流畅的交互体验。
  8. 消息管理:获取和管理对话消息,便于查看历史对话记录。
  9. 评估功能:评估模型性能,帮助用户了解和优化模型的表现。

详细的API文档可以参考docs/API.md,其中包含了每个API的详细说明、请求参数和响应示例。

错误处理

WeKnora API使用标准的HTTP状态码表示请求状态,并返回统一的错误响应格式。当请求失败时,API会返回一个JSON对象,包含successerror等字段,其中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混合搜索流程

该图展示了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智能问答的界面效果,包括用户的问题、系统的回答以及相关的参考来源。

实战案例:构建一个完整的智能问答应用

为了帮助开发者更好地理解和使用WeKnora API,下面我们将通过一个实战案例,展示如何构建一个完整的智能问答应用。该应用将实现从知识库创建、知识上传到智能问答的整个流程。

案例概述

本案例将构建一个基于WeKnora的智能问答应用,该应用能够:

  1. 创建一个租户,获取API Key。
  2. 创建一个知识库,配置分块策略和模型参数。
  3. 上传一个PDF文件作为知识内容。
  4. 创建一个会话,进行多轮智能问答。
  5. 获取会话历史消息,查看对话记录。

实现步骤

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调用的性能和稳定性,可以采用以下高级技巧:

  1. 批量操作:对于需要创建多个知识库或上传多个文件的场景,可以考虑使用批量API(如果支持)或合理组织并发请求,提高处理效率。
  2. 缓存策略:对于频繁访问的知识库信息、模型信息等,可以在客户端进行缓存,减少API调用次数。
  3. 异步处理:对于文件上传、知识解析等耗时操作,可以采用异步处理的方式,避免阻塞主线程。WeKnora的API通常会返回任务ID,客户端可以通过轮询或回调的方式获取处理结果。
  4. 连接池:使用HTTP连接池,复用TCP连接,减少连接建立和关闭的开销。
  5. 错误重试:对于偶发性的网络错误或服务器错误,可以实现指数退避的重试机制,提高请求的成功率。

总结与展望

WeKnora API为开发者提供了强大的语义检索和智能问答能力,通过本文的介绍,相信你已经掌握了WeKnora API的基本使用方法和核心功能调用技巧。从租户创建、知识库管理到知识上传、智能问答,WeKnora提供了一套完整的接口,帮助你快速构建上下文感知的智能应用。

未来,WeKnora将继续优化API性能,增加更多高级功能,如多模态知识处理、个性化推荐等,为开发者提供更好的体验。如果你在使用WeKnora API的过程中遇到任何问题,可以参考官方文档docs/API.md,或查阅源代码client/获取更多示例和细节。

最后,希望本文能够帮助你更好地理解和使用WeKnora API,让你的应用具备强大的文档理解和智能交互能力。如果你觉得本文对你有帮助,欢迎点赞、收藏、关注,获取更多关于WeKnora的技术文章和最佳实践。

登录后查看全文
热门项目推荐
相关项目推荐