union_kb_ingest 1.0.1 → 1.0.3

package/README.md

@@ -8,7 +8,7 @@
 2. 通过 Docling slim 的离线文本解析能力生成统一 Markdown 中间格式。
 3. 按章节、场景、规则、指标等粒度切割。
 4. 可选调用大模型，把内容整理为项目知识库规范要求的 Markdown 文件。
-5. 默认生成 `status: draft` 草稿，不进入现有 RAG 检索。
+5. 默认生成可直接交给知识库项目使用的 `status: active` Markdown 文件。
 
 启用大模型时，工具会把 `prompts/联合运维知识库建立规范.md` 作为格式和质量约束放入提示词，要求模型依据原文语义判断业务场景、模块、角色、标签和风险等级。代码中的启发式生成只作为未启用大模型或调用失败时的兜底，不使用预设业务关键词去指导大模型输出。
 
@@ -37,13 +37,13 @@ python -m pip install -r requirements.txt
 input/
 ```
 
-生成草稿：
+生成知识库文件：
 
 ```bash
 python ingest.py draft
 ```
 
-如果 `drafts/` 中已有草稿文件，命令会先询问是否覆盖。选择 `y` 后会清空 `drafts/`、`approved/` 和 `result/` 中已有生成文件，再重新生成；选择其他内容会直接退出，避免多次生成结果相互影响。
+如果 `result/` 中已有生成文件，命令会先询问是否覆盖。选择 `y` 后会清空 `result/` 中已有生成文件，再重新生成；选择其他内容会直接退出，避免多次生成结果相互影响。
 
 只解析为中间 Markdown：
 
@@ -51,50 +51,55 @@ python ingest.py draft
 python ingest.py parse
 ```
 
-校验草稿：
+校验生成结果：
 
 ```bash
 python ingest.py validate
 ```
 
-审核后复制到知识库：
+默认目录为 `input/`、`parsed/` 和 `result/`。只有需要处理其他目录时，才使用 `--input` 或 `--output` 覆盖。
 
-```bash
-python ingest.py promote
-```
+`draft` 默认按 `config/config.yaml` 的 `draft.max_chars` 控制单次送入模型的原文长度，并额外提供文档目录和相邻片段摘要作为辅助上下文。这样可以降低私有模型单轮负载，同时尽量保留前后章节关系。命令行仍可用 `--max-chars` 临时覆盖。
 
-默认目录为 `input/`、`parsed/`、`drafts/`、`approved/` 和 `result/`。只有需要处理其他目录时，才使用 `--input`、`--output` 或 `--result-dir` 覆盖。
+每条知识库文件会写入分类画像元数据：`category`、`category_description` 和 `category_keywords`。这些字段优先来自源文件一级标题、首页标题、章节目录和文件名，用于标识一个批次/业务场景的大类。后续 RAG 入库和检索时，应把这些字段写入向量库 metadata，并用于分类过滤、查询路由或重排加权，降低不同场景之间因为相似词命中而串场的概率。
+
+生成结果会按原始输入遍历顺序写入 `source_order`，并用 `000001-...md` 这样的文件名前缀保持目录排序与原文从上到下的顺序一致。页码只写入 Front Matter 的 `source_pages`/`source_trace` 和正文 `## 5. 来源依据`，不会进入正文 `## 1. 核心内容` 到 `## 4. 关联能力`。
 
 ## 大模型配置
 
-默认不强制调用大模型，会使用启发式模板生成 `draft` 文件。
+默认不强制调用大模型，会使用启发式模板生成知识库文件。
 
 如果要启用大模型整理，修改 `config/config.yaml`：
 
 ```yaml
 llm:
   enabled: true
-  base_url: "https://your-model-endpoint"
-  api_key: "your-api-key"
-  model: "your-model"
+  base_url: "https://open.bigmodel.cn/api/paas/v4/"
+  api_key: "your-zhipu-api-key"
+  model: "glm-4.7"
   timeout_seconds: 120
-  max_tokens: 4096
+  max_tokens: 8192
   temperature: 0.1
+
+draft:
+  max_chars: 3600
+  context_chars: 800
+  outline_max_sections: 40
 ```
 
 也可以继续使用环境变量覆盖配置文件：
 
 ```bash
 export KB_LLM_ENABLED=true
-export KB_LLM_BASE_URL="https://your-model-endpoint"
-export KB_LLM_API_KEY="your-api-key"
-export KB_LLM_MODEL="your-model"
+export KB_LLM_BASE_URL="https://open.bigmodel.cn/api/paas/v4/"
+export KB_LLM_API_KEY="your-zhipu-api-key"
+export KB_LLM_MODEL="glm-4.7"
 ```
 
-`base_url` 必须填写完整的大模型调用地址，工具不会自动拼接任何路径。工具不 import 项目 `src` 代码。
+工具通过 Z.AI 新版 Python SDK 调用中文智谱开放平台 GLM，依赖固定为 `zai-sdk==0.2.2`，客户端固定使用官方中文写法 `from zai import ZhipuAiClient`，`base_url` 使用 `https://open.bigmodel.cn/api/paas/v4/`。工具不再包含旧 `zhipuai` SDK、国际版 `ZaiClient` 或 OpenAI 调用路径，也不 import 项目 `src` 代码。
 
 ## 与线上项目的关系
 
-这个工具只产出符合规范的 `*.md` 文件。确认无误后，人工把 `status: draft` 改为 `active`，再放入 `result/`，后续由线上知识库加载流程处理。
+这个工具只产出符合规范的 `*.md` 文件到 `result/`，后续由线上知识库加载流程处理。
 
 建议线上打包时排除整个 `tools/kb_ingest` 目录。

package/app_config.py

@@ -24,6 +24,13 @@ class LlmConfig:
     temperature: float = 0.1
 
 
+@dataclass(frozen=True)
+class DraftConfig:
+    max_chars: int = 3600
+    context_chars: int = 800
+    outline_max_sections: int = 40
+
+
 @lru_cache(maxsize=1)
 def get_llm_config() -> LlmConfig:
     raw = _read_config().get("llm", {})
@@ -41,6 +48,19 @@ def get_llm_config() -> LlmConfig:
     )
 
 
+@lru_cache(maxsize=1)
+def get_draft_config() -> DraftConfig:
+    raw = _read_config().get("draft", {})
+    if not isinstance(raw, dict):
+        raw = {}
+
+    return DraftConfig(
+        max_chars=_env_int("KB_DRAFT_MAX_CHARS", raw.get("max_chars"), 3600),
+        context_chars=_env_int("KB_DRAFT_CONTEXT_CHARS", raw.get("context_chars"), 800),
+        outline_max_sections=_env_int("KB_DRAFT_OUTLINE_MAX_SECTIONS", raw.get("outline_max_sections"), 40),
+    )
+
+
 def _read_config() -> Dict[str, Any]:
     path = Path(os.environ.get("KB_INGEST_CONFIG", DEFAULT_CONFIG_PATH))
     if not path.exists():

package/config/config.yaml

@@ -1,8 +1,13 @@
 llm:
-  enabled: true
+  enabled: false
   timeout_seconds: 120
-  max_tokens: 4096
+  max_tokens: 8192
   temperature: 0.1
-  api_key: "15f066c4509845038027ea5746524af5.w4CLSC6ODiKVC1wK"          # GLM API Key
-  model: "glm-4.7-flash"                 # 模型名称，可选: glm-4, glm-4-plus, glm-4-flash 等
-  base_url: "https://open.bigmodel.cn/api/paas/v4/"  # 模型服务地址
+  api_key: "your-zhipu-api-key"
+  model: "GLM-4.7-Flash"
+  base_url: "https://open.bigmodel.cn/api/paas/v4/"
+
+draft:
+  max_chars: 3600
+  context_chars: 800
+  outline_max_sections: 40

package/ingest.py

@@ -2,16 +2,18 @@
 from __future__ import annotations
 
 import argparse
-import shutil
 import sys
 from pathlib import Path
+from typing import List
 
 CURRENT_DIR = Path(__file__).resolve().parent
 if str(CURRENT_DIR) not in sys.path:
     sys.path.insert(0, str(CURRENT_DIR))
 
+from app_config import get_draft_config
 from normalizer import normalize_block
 from parser import iter_input_files, parse_document
+from schemas import ParsedBlock
 from splitter import split_blocks
 from validator import validate_dir
 from writer import write_item
@@ -38,26 +40,36 @@ def cmd_parse(args) -> int:
 def cmd_draft(args) -> int:
     input_path = Path(args.input)
     output_dir = Path(args.output)
-    approved_dir = Path(args.approved_dir)
-    result_dir = Path(args.result_dir)
 
     existing = _list_effective_files(output_dir)
-    if existing and not _confirm_overwrite(output_dir, approved_dir, result_dir, existing):
+    if existing and not _confirm_overwrite(output_dir, existing):
         print("aborted. existing files were kept.")
         return 0
 
     if existing:
-        _clear_generated_files(output_dir, approved_dir, result_dir)
+        _clear_generated_files(output_dir)
 
     output_dir.mkdir(parents=True, exist_ok=True)
 
     total_items = 0
+    source_order = 0
+    draft_config = get_draft_config()
+    max_chars = args.max_chars or draft_config.max_chars
     files = iter_input_files(input_path)
     for path in files:
         parsed = parse_document(path)
-        blocks = split_blocks(parsed.blocks, max_chars=args.max_chars)
+        blocks = split_blocks(parsed.blocks, max_chars=max_chars)
+        blocks = _attach_block_context(
+            blocks,
+            context_chars=draft_config.context_chars,
+            outline_max_sections=draft_config.outline_max_sections,
+        )
         for block in blocks:
-            for item in normalize_block(block, status="draft"):
+            for item in normalize_block(block, status=args.status):
+                source_order += 1
+                item.source_order = source_order
+                item.source_pages = sorted(set(block.pages))
+                item.source_trace = _source_trace(block)
                 write_item(item, output_dir)
                 total_items += 1
         print(f"drafted: {path} blocks={len(blocks)}")
@@ -76,15 +88,11 @@ def _list_effective_files(path: Path) -> list[Path]:
 
 def _confirm_overwrite(
     output_dir: Path,
-    approved_dir: Path,
-    result_dir: Path,
     existing: list[Path],
 ) -> bool:
     print(f"found {len(existing)} existing file(s) in {output_dir}.")
     print("Continuing will delete existing generated files under:")
     print(f"- {output_dir}")
-    print(f"- {approved_dir}")
-    print(f"- {result_dir}")
     answer = input("Overwrite and continue? [y/N]: ").strip().lower()
     return answer in {"y", "yes"}
 
@@ -96,6 +104,84 @@ def _clear_generated_files(*dirs: Path) -> None:
             print(f"deleted: {path}")
 
 
+def _attach_block_context(
+    blocks: List[ParsedBlock],
+    context_chars: int,
+    outline_max_sections: int,
+) -> List[ParsedBlock]:
+    if context_chars <= 0:
+        return blocks
+
+    outline = _document_outline(blocks, outline_max_sections)
+    output: List[ParsedBlock] = []
+    for idx, block in enumerate(blocks):
+        parts = []
+        if outline:
+            parts.append(f"文档章节目录：\n{outline}")
+        if block.category_description:
+            parts.append(
+                "知识大类说明：\n"
+                f"大类：{block.category}\n"
+                f"说明：{block.category_description}\n"
+                f"关键词：{', '.join(block.category_keywords)}"
+            )
+        if idx > 0:
+            parts.append(
+                "上一片段摘要：\n"
+                f"章节：{blocks[idx - 1].source_section}\n"
+                f"{_compact_context_text(blocks[idx - 1].content, context_chars // 2)}"
+            )
+        if idx + 1 < len(blocks):
+            parts.append(
+                "下一片段摘要：\n"
+                f"章节：{blocks[idx + 1].source_section}\n"
+                f"{_compact_context_text(blocks[idx + 1].content, context_chars // 2)}"
+            )
+        output.append(ParsedBlock(
+            source_doc=block.source_doc,
+            source_section=block.source_section,
+            content=block.content,
+            pages=block.pages,
+            order=block.order,
+            context="\n\n".join(parts),
+            category=block.category,
+            category_description=block.category_description,
+            category_keywords=block.category_keywords,
+        ))
+    return output
+
+
+def _document_outline(blocks: List[ParsedBlock], max_sections: int) -> str:
+    sections = []
+    seen = set()
+    for block in blocks:
+        section = block.source_section.strip()
+        if not section or section in seen:
+            continue
+        seen.add(section)
+        sections.append(f"- {section}")
+        if len(sections) >= max_sections:
+            remaining = len(blocks) - len(sections)
+            if remaining > 0:
+                sections.append(f"- ... 其余 {remaining} 个片段")
+            break
+    return "\n".join(sections)
+
+
+def _compact_context_text(text: str, limit: int) -> str:
+    compact = " ".join(text.split())
+    if limit <= 0 or len(compact) <= limit:
+        return compact
+    return compact[:limit].rstrip() + "..."
+
+
+def _source_trace(block: ParsedBlock) -> str:
+    parts = [f"section={block.source_section}"]
+    if block.pages:
+        parts.append(f"pages={','.join(map(str, sorted(set(block.pages))))}")
+    return "; ".join(parts)
+
+
 def cmd_validate(args) -> int:
     issues = validate_dir(Path(args.input))
     for issue in issues:
@@ -104,20 +190,6 @@ def cmd_validate(args) -> int:
     return 1 if any(i.level == "error" for i in issues) else 0
 
 
-def cmd_promote(args) -> int:
-    input_dir = Path(args.input)
-    result_dir = Path(args.result_dir)
-    result_dir.mkdir(parents=True, exist_ok=True)
-    count = 0
-    for path in sorted(input_dir.rglob("*.md")):
-        target = result_dir / path.name
-        shutil.copy2(path, target)
-        count += 1
-        print(f"promoted: {path} -> {target}")
-    print(f"done. promoted={count}")
-    return 0
-
-
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Offline document-to-knowledge Markdown generator.")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -129,21 +201,15 @@ def build_parser() -> argparse.ArgumentParser:
 
     draft_cmd = sub.add_parser("draft", help="Generate draft knowledge files.")
     draft_cmd.add_argument("--input", default=str(CURRENT_DIR / "input"))
-    draft_cmd.add_argument("--output", default=str(CURRENT_DIR / "drafts"))
-    draft_cmd.add_argument("--approved-dir", default=str(CURRENT_DIR / "approved"))
-    draft_cmd.add_argument("--result-dir", default=str(CURRENT_DIR / "result"))
-    draft_cmd.add_argument("--max-chars", type=int, default=8000)
+    draft_cmd.add_argument("--output", default=str(CURRENT_DIR / "result"))
+    draft_cmd.add_argument("--status", default="active", choices=["draft", "active"])
+    draft_cmd.add_argument("--max-chars", type=int, default=None)
     draft_cmd.set_defaults(func=cmd_draft)
 
     validate_cmd = sub.add_parser("validate", help="Validate generated Markdown files.")
-    validate_cmd.add_argument("--input", default=str(CURRENT_DIR / "drafts"))
+    validate_cmd.add_argument("--input", default=str(CURRENT_DIR / "result"))
     validate_cmd.set_defaults(func=cmd_validate)
 
-    promote_cmd = sub.add_parser("promote", help="Copy reviewed files to result.")
-    promote_cmd.add_argument("--input", default=str(CURRENT_DIR / "approved"))
-    promote_cmd.add_argument("--result-dir", default=str(CURRENT_DIR / "result"))
-    promote_cmd.set_defaults(func=cmd_promote)
-
     return parser