01
解析：记录页边界
PDF 逐页解析，页标记写入 Markdown，后续切块可以引用页码。
给 Agent 插一块知识库。
你
把「产品手册.docx」和「部署手册.pdf」收进产品库，然后回答：嵌入模型怎么标定？
调用
upload_document产品手册.docx → doc_8f2a · is_duplicate false
调用
upload_document部署手册.pdf → doc_1c7e · is_duplicate false
调用
get_document_statusstage indexed · chunks 184 · searchable true
调用
searchfit strong · 38 candidates → 4 survived
部署手册.pdf
p.7 · similarity 0.712
嵌入维度建议不超过 2000，推荐 1024。超过之后 pgvector 建不了 HNSW，检索会退化成精确扫描。
Agent
答案是：建议不超过 2000，推荐 1024，超过后建不了 HNSW。
来源：部署手册.pdf，p.7，五、嵌入模型与维度
示例会话
REST 200 MB · MCP 32 MB
01 / 工具
11 个工具，
覆盖知识库全流程。
接入、上传、解析、管理、检索都在 MCP 工具中。Agent 按状态调用，每一步都有明确的返回。
工具契约带指纹 surface_fingerprint。
请求使用 Authorization: Bearer <API Key> 鉴权。
02 / 返回
先给判定，
再给原文。
响应包含 summary、distribution、decision 和命中片段。
Agent 可以据此判断资料是否相关，并决定引用哪些内容。
POST
/api/v1/search
200 OK
QUERY嵌入模型怎么标定？
summary
候选 38 条、其中 5 条高于基线 0.531，收敛后留 4 条，收敛参数按程序建议：资料很对得上，按每篇最相关的收敛。
distributionSTRONG
decision
keep 4min_score 0.531per_doc null
decided_by suggesteddropped 33unscored_kept 0
hits
- 01部署手册.pdfp.70.712vector
- 02检索设计-v2.mdp.30.664vector
- 03产品手册.docx—0.588vector
- 04评测-检索质量.md—0.551fulltext
next_offset
4
fit四档：strong 相关 · weak 部分相关 · none 不相关 · unknown 未知score是融合分，similarity是余弦相似度basis标明命中来自vector或fulltext
03 / 页码
每条命中，
都能回到原页。
解析时记录页边界，切块时保留页码，检索命中返回页码与标题路径。PDF 还可以按页查看原图。
03 / 页码 · 从解析到命中
解析 · 页标记写入 Markdown
- #03 · p.6四、对象存储与桶名
- #04 · p.7五、嵌入模型与维度命中候选
- #05 · p.7嵌入维度建议不超过 2000……
- #06 · p.8六、检索与重排
- #07 · p.8七、重排的适用场景
切块 · 页码写入切块
检索 · 原文、页码、标题路径返回
02
切块：保留页码
每个切块记录所在页与标题路径，命中后可以直接定位。
03
检索：带出处返回
命中包含原文、页码、标题路径和 chunk id；PDF 可按页查看原图。
get_document_pages 按页读取原文与页图，单次支持 1 至 50 页。
04 / 双格式
原件和 Markdown，
都保留。
上传的文件原样存储，解析结果转换为 Markdown。核对版式用原件，检索与切块用 Markdown。
original
PDF 和图片类文档可以按页查看原图，用于版本核对。
- 原件按内容哈希存储，用于下载与预览；页图按需渲染。
- Markdown切块、页标记和向量化都基于这份产物。
- 取用
get_document_content的format参数选择原件或 Markdown。
MDdoc_1c7e.mdmarkdown
## 五、嵌入模型与维度
模型身份由模型注册表承担，不写进环境变量。
<!-- page:7 -->
嵌入维度建议不超过 2000，推荐 1024。超过之后
pgvector 建不了 HNSW，检索会退化成精确扫描。
## 六、检索与重排更换解析器后，用 reparse_document 重新解析。
get_document_content(document_id, format="original")取原件get_document_content(document_id, format="markdown")取解析产物200 MB REST 上传上限 · 32 MB MCP 单次05 / 调参
每次检索，
参数由 Agent 决定。
检索模式和参数随请求传入。分布会给出建议值，Agent 可以直接采用，也可以按需要调整。
distributionSTRONG
38 candidates · 4 survived
0.37baseline 0.5310.712
资料吻合度高，按每篇最相关的结果收敛。
分布、基线与建议值在同一次返回中。
mode
向量 + 词面，RRF 融合
keep
4
一页返回条数
min_score
0.531
余弦相似度下限
per_doc
null
每篇文档最多条数
decided_by
suggested
参数来源
下一次调用
{"keep": 4, "min_score": 0.531, "per_doc": null}
采用分布建议的参数。
06 / 解析服务
解析和向量化，
先用免费额度。
MinerU、PaddleOCR 和硅基流动都提供免费额度；文字型 PDF 和 Office 文件也可以在本地解析。
01文件PDF · Word · 图片 · 表格
02文件探测文字型 / 扫描件 / 混合
03解析引擎按文件选择引擎
04Markdown页标记与切块
05BGE-M31024 维向量
云端 · 版面还原免费额度
MinerU
PDF、Office、图片的版面还原，云端 API，默认 VLM 模型。
- 额度
- 1000 页 / 天
- 类型
- 云端 · 可选
云端 · 扫描件免费额度
PaddleOCR
扫描件与混合型 PDF 的 OCR，异步任务逐页处理。
- 额度
- 免费额度
- 类型
- 云端 · 可选
API · 向量免费额度
硅基流动 · BGE-M3
OpenAI 兼容的嵌入接口，BGE-M3 1024 维，也可接入 BGE Reranker。
- 模型
BAAI/bge-m3- 类型
- API · 可选
本地 · 解析无需额度
本地直提
文字型 PDF、.docx、.pptx、Markdown 与文本在本地解析。
- 范围
- 无版面还原
- 许可
- MIT · 自托管
07 / 部署
一条命令，
启动服务。
Docker 启动 PostgreSQL、MinIO、后端、MCP 与前端。登记嵌入模型后，用 API Key 接入 Agent。
干净机器 · Docker Compose
git clone https://github.com/kkomia/kybase.git
cd kybase
docker compose -f deploy/docker-compose.yml up -d --build
# 界面 http://localhost:8080
# MCP http://localhost:8765/mcp
# 健康 http://localhost:8080/api/v1/healthMCP 客户端 · Streamable HTTP
{
"mcpServers": {
"kybase": {
"type": "http",
"url": "http://kb.example.com:8765/mcp",
"headers": { "Authorization": "Bearer <你的 API Key>" }
}
}
}- 01
启动容器
PostgreSQL（pgvector）、MinIO、后端、MCP 与前端。
- 02
登记嵌入模型
在「模型」页登记嵌入模型。
- 03
创建知识库
上传文件，摄入流程自动执行。
- 04
接入 Agent
创建 API Key，配置 MCP 或 Skill。
Skill 包在仓库 skills/，适用于只有 shell 与 HTTP 的环境。
完整部署说明见 部署指南。