WeKnora

通过 WeKnora REST API 实现知识库文档的导入与检索。

环境配置

1. 在 WeKnora Web 界面（账户设置页面）中获取您的 API Key
2. 配置环境变量：

export WEKNORA_BASE_URL="https://your-server.com/api/v1"
export WEKNORA_API_KEY="sk-your-api-key"

将上述内容添加至 ~/.zshrc 或 ~/.bashrc 中，以在各终端会话间持久化生效。

凭证校验

在发起任何 API 调用前，请先验证凭证。若未设置，则立即中止并提示用户。

if [ -z "$WEKNORA_BASE_URL" ] || [ -z "$WEKNORA_API_KEY" ]; then
  echo "缺少 WeKnora 凭证。请按“环境配置”步骤设置 WEKNORA_BASE_URL 和 WEKNORA_API_KEY。"
  exit 1
fi

API 调用模板

所有请求均发送至 $WEKNORA_BASE_URL，并携带一组通用请求头。定义如下辅助函数：

wk_api() {
  local method="$1" endpoint="$2" body="$3"
  curl -s -X "$method" "$WEKNORA_BASE_URL/$endpoint" 
    -H "X-API-Key: $WEKNORA_API_KEY" 
    -H "Content-Type: application/json" 
    -H "X-Request-ID: $(uuidgen 2>/dev/null || date +%s)" 
    ${body:+-d "$body"}
}

文件上传请直接使用 curl -F（multipart/form-data 格式）。

API 使用决策表

常用工作流

上传文件并等待解析完成

# 1. 查找目标知识库
wk_api GET "knowledge-bases"
# -> 从 data[].id 中选取 kb_id

# 2. 上传文件
curl -s -X POST "$WEKNORA_BASE_URL/knowledge-bases//knowledge/file" 
  -H "X-API-Key: $WEKNORA_API_KEY" 
  -F 'file=@document.pdf' -F 'enable_multimodel=true'
# -> 从响应 data.id 中获取 knowledge_id

# 3. 轮询直至解析完成
wk_api GET "knowledge/"
# -> 持续调用，直到 data.parse_status == "completed"

导入网页 URL

wk_api POST "knowledge-bases//knowledge/url" 
  '{"url": "https://example.com/article", "enable_multimodel": true}'
# -> 同文件上传，轮询 knowledge/:id 获取状态

写入 Markdown 知识条目

wk_api POST "knowledge-bases//knowledge/manual" 
  '{"title": "Meeting Notes", "content": "# Q1 ReviewnnKey points..."}'

知识搜索

# 单知识库混合搜索（向量 + 关键词）
wk_api GET "knowledge-bases//hybrid-search" 
  '{"query_text": "deployment process", "match_count": 5}'

# 跨知识库语义搜索
wk_api POST "knowledge-search" 
  '{"query": "deployment process", "knowledge_base_ids": ["kb-1", "kb-2"]}'

浏览与读取知识库内容

# 列出知识条目（分页）
wk_api GET "knowledge-bases//knowledge?page=1&page_size=20"

# 获取单个条目的完整详情
wk_api GET "knowledge/"

核心响应字段说明

知识库对象（GET /knowledge-bases）：data[] — 包含 id、name、description、type（document | faq）、embedding_model_id、knowledge_count、chunk_count、is_processing、created_at。

知识条目对象（GET /knowledge/:id）：data — 包含 id、title、description（自动生成摘要）、type（file | url | manual）、parse_status、enable_status、file_name、file_type、file_size、source（来源 URL）、created_at、processed_at、error_message。

搜索结果（hybrid-search）：data[] — 包含 id、content（文本块内容）、score（相关性得分，范围 0–1）、knowledge_id、knowledge_title、knowledge_filename、chunk_index、chunk_type（text | summary | image）、match_type、metadata。

分页列表响应（GET .../knowledge）：包含 data[] 及 total、page、page_size 字段。

枚举值说明

• parse_status： pending → processing → completed | failed
• enable_status： enabled | disabled（知识条目在成功解析后自动变为 enabled）
• type（知识条目）： file（已上传文件）、url（网页导入）、manual（Markdown 手动录入）
• type（知识库）： document（标准文档型）、faq（FAQ 对型）
• chunk_type： text（常规文本块）、summary（自动生成摘要）、image（图像块）

分页机制

• 偏移分页（GET .../knowledge、GET /sessions）：使用 page 和 page_size 查询参数；响应中包含 total 字段，可用于计算总页数。
• 混合搜索（hybrid-search）：最多返回 match_count 条结果（不支持传统分页；如需更多结果，请增大 match_count 值）。

注意事项

• GET /knowledge-bases/:id/hybrid-search 使用 GET 方法，但**必须携带 JSON 请求体** — 请在 curl 中使用 -d '{...}' 显式传入。
• 上传完成后，知识条目的 enable_status 初始为 disabled；待 parse_status 变为 completed 后，系统自动将其设为 enabled。
• 文件上传采用 multipart/form-data 编码格式，而非 JSON；请使用 curl -F 'file=@path' 方式上传。
• file_type 由系统根据上传文件自动识别（支持 pdf、docx、xlsx、pptx、txt、md、csv、html 等格式）。
• 搜索结果的 score 取值范围为 0–1，数值越高表示相关性越强；可通过调整 vector_threshold（默认约 0.5）过滤低质量匹配项。
• 当 parse_status 为 failed 时，请先检查 error_message 字段获取失败原因，再决定是否重试 POST /knowledge/:id/reparse。

错误处理

所有错误响应均返回如下结构：

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "可读性描述",
    "details": "可选的附加信息"
  }
}