kbase

最小可安装的 Typer 命令行项目骨架。

安装

# 方式 1：同步项目依赖（含开发依赖）
uv sync --extra dev

# 方式 2：可编辑安装
uv pip install -e ".[dev]"

开发

uv run pytest tests/test_cli_help.py -q

使用

kbase --help
kbase version

文档

• docs/打包与交付（kbase-cli）.md：打包交付给他人使用的完整流程（含依赖安装、.env、检查点）
• docs/发布到PyPI（kbase-cli）.md：发布到 PyPI 的标准流程（对齐 scripts/build.* 与 scripts/publish_pypi.*）

最小化适配（mineru-cloud 默认）

当前默认解析器为 mineru-cloud，保持现有 CLI 体验不变，仍使用：

• kbase kb create/use/list
• kbase add file/dir
• kbase ask

最小环境变量（推荐）

# 必填：MinerU Cloud
export MINERU_API_TOKEN="your_mineru_token"

# 必填：LLM
export LLM_API_KEY="your_llm_key"
export LLM_BASE_URL="https://your-openai-compatible-base-url/v1"
export LLM_MODEL="gpt-4o-mini"
export VISION_MODEL="gpt-4o-mini"

# Embedding（默认在线）
export EMBED_PROVIDER="online"
export EMBED_MODEL="text-embedding-3-large"
export EMBED_DIM="3072"
export EMBED_BASE_URL="$LLM_BASE_URL"
export EMBED_API_KEY="$LLM_API_KEY"

可选：本地 Ollama bge-m3

export EMBED_PROVIDER="ollama"
export EMBED_BASE_URL="http://localhost:11434/v1"
export EMBED_MODEL="bge-m3"
export EMBED_DIM="1024"
export EMBED_API_KEY="ollama"

端到端命令示例

# 1) 初始化
kbase init

# 2) 创建并切换知识库
kbase kb create mykb --use

# 3) 入库目录（支持 pdf/doc/docx/ppt/pptx/图片）
kbase add dir "/Users/you/Desktop/test-docs" --recursive

# 4) 提问
kbase ask "请总结这个目录里的核心结论"

新增诊断与可观测命令

查看生效配置（脱敏）

kbase config show

输出会脱敏展示 LLM_API_KEY / MINERU_API_TOKEN / EMBED_API_KEY，用于排查配置是否生效。

查看知识库状态（增强）

kbase status

status 现在会展示：

• docs：文档数量
• chunks：总块数
• doc_status_success/failed/pending：处理状态分布
• parse_cache_entries：解析缓存条目
• storage_files：存储文件数
• last_updated：最近更新时间