统计概览

功能介绍与使用说明

展示当前知识库的全局统计：图纸总数、项目数、各专业分布、图层 / 块数量等。

  • 点击「刷新统计」从 API 获取最新统计。
  • 统计基于已构建的 RDF 知识库；新增图纸或重建后请刷新查看。
  • 统计异常时可检查 /health 接口的 rdf_loaded 字段确认 RDF 是否加载完成。

智能查询

功能介绍与使用说明

两种查询方式：自然语言（关键词启发式解析，非 LLM，结果附带证据）；SPARQL（直接对 RDF 数据查询）。

  • 自然语言：输入如「哪些项目用了暖通系统？」后点击「查询」。
  • SPARQL：切换到 SPARQL 模式，输入标准 SPARQL 语句（受服务端 DWG_KB_SPARQL_MAX_CHARS / 默认行数限制）。
  • 所有回答均包含 evidence 字段，标明结果数据来源。

图纸浏览

功能介绍与使用说明

浏览知识库中的图纸列表，支持按专业筛选（建筑 / 结构 / 暖通 / 电气 / 给排水 / 机械 / 工艺）。

  • 不选专业时列出全部图纸（分页返回，每页最多 1000 条）。
  • 选择专业后点击「搜索」过滤。
  • 列表含图纸名称、ID、专业、项目、版本等，名称可复制到「设计演进」/「跨专业关联」使用。

设计演进

功能介绍与使用说明

追踪图纸的版本演进链。版本号由文件名模式自动识别（_t3、(1)、2023.01.09 等）。

  • 输入图纸名称，点击「追踪演进」查看该图纸的版本链。
  • 点击「所有演进链」列出知识库中全部演进链。
  • 图纸名称可从「图纸浏览」结果中复制。

跨专业关联

功能介绍与使用说明

发现图纸之间的跨专业协调关系，基于块引用（BlockRef）、矢量连通性与图号互引（callouts）。

  • 「查找关联」：输入图纸名称，查看引用它 / 被它引用的图纸。
  • 「协调矩阵」：查看各专业之间引用关系的数量矩阵。
  • 「共享图层」：查看不同专业共享的图层（潜在协调点）。

图谱可视化

功能介绍与使用说明

Sigma.js 交互式图谱：节点为图纸（按专业着色）、块、项目等，边包含引用（references）、连通（connected_to）等关系。

  • 切换到本页自动加载图谱，需先完成构建（生成 graph.html）。
  • 若显示「图谱未构建」，请先到「构建知识库」完成构建，再重新进入本页。
  • 可鼠标拖拽平移、滚轮缩放探索；重建后重新进入本页加载最新图谱。

双轨校验

视觉轨（渲染 + VLM）与精确轨（ezdxf 硬数据）比对，冲突时以数据为准。

功能介绍与使用说明
  • 输入图纸 ID 或名称（如 A-01 或「平面图」），附加问题可选，供 VLM 参考。
  • 「渲染图片」：仅将图纸渲染为 PNG 供目视检查。
  • 「运行校验」：执行完整双轨校验，输出 JSON 报告（房间名 / 标题 / 专业 / 图号四类声明，每项含 evidence；冲突标记 corrected）。大图纸走后台任务并自动轮询进度。
  • 「待审清单」：汇总高风险提取、ACAD_PROXY 警告、校验冲突、低置信度项，供人工复核（只列清单，不自动处理）。
  • VLM 提供方由服务端 DWG_KB_VLM_PROVIDER 决定（默认离线 mock）。

        


        
        

            
构建知识库

            
选择 DWG 源目录或提取结果目录，并选择提取方式。

            

                功能介绍与使用说明
                
一键「提取 + 构建」：DWG →（dwg2dxf 转换）→ 提取 JSON → RDF 知识库 + 图谱。全程后台运行，带进度条与日志。

                
    
                    
  • 「选择目录…」：选 DWG 源目录（含 .dwg 文件）或已有提取结果目录；留空使用默认 ./dwg-extract。目录会被记住，下次自动填充。
    • 
                    
  • 模式选择：自动（无元数据时先提取）/ 继续提取（跳过已处理、补齐缺失）/ 全部提取（重新提取所有 DWG，有确认提示）/ 仅构建（不提取，只用已有结果建库）。
    • 
                    
  • 点击「开始构建」，完成后自动刷新统计与图谱。
    • 
                    
  • 转换 DWG 需系统安装 dwg2dxf（libredwg）。
    • 
                

            

            

                
                
            

            

                
                
            

            
            

        


        
        

            
使用指南

            

                
1. 系统简介

                
本系统是基于本体（ontology）的 CAD DWG 知识图谱：批量解析历年设计图纸（DWG），构建可查询、可追溯、可可视化的知识底座。核心能力：

                
    
                    
  • 从 DWG 中提取图纸元数据（图层、块、文字、尺寸、图号互引、实体连通性）并诊断解析风险；
    • 
                    
  • 双轨校验：视觉轨（渲染 + 视觉模型 VLM）与精确轨（ezdxf 硬数据）相互比对，冲突时以硬数据为准；
    • 
                    
  • 构建 RDF 知识图谱（NetworkX），支持自然语言 / SPARQL 查询、版本演进追踪、跨专业关联分析；
    • 
                    
  • 对外提供 Web UI、REST API、MCP（供 AI 客户端）与 Neo4j 导出。
    • 
                


                
2. 操作流水线（Pipeline）

                
数据从 DWG 源文件到知识图谱的完整链路（顺序有依赖，不可颠倒）：

                
 DWG 源文件（按年份目录，如 raw/2016 … 2025）
   │  ① 提取 extract：dwg2dxf 转换 → ezdxf 解析
   ▼
 <stem>.json + <stem>.md   （默认 <root>/dwg-extract/，保留目录结构）
   │     含 dimensions / callouts / block_refs / connections / diagnostics
   ├──② 渲染 render（可选，视觉轨）──▶ PNG/SVG + tiles 瓦片 + manifest
   ├──③ 双轨校验 verify ────────────▶ <stem>.verify.json 裁决报告
   ├──④ 诊断 diagnose / 待审 review ─▶ 风险统计 / 人工复核清单
   ▼
 ⑤ 构建 build：OntologyPopulator
   ▼
 knowledge.trig（RDF 三元组）+ knowledge.json（NetworkX）+ graph/graph.html
   ▼
 ⑥ 消费：query / serve（API + Web UI）/ mcp（AI 客户端）/ export-neo4j


                

                    
1提取
extract

                    
→

                    
2渲染(可选)
render

                    
→

                    
3双轨校验
verify

                    
→

                    
4诊断/待审
diagnose

                    
→

                    
5构建
build

                    
→

                    
6查询/服务
query serve

                

                
另有「后台常驻」选项：autobuild（CPU 空闲时自动跑 ①+⑤ 的守护进程）与 service / systemd（服务化部署）。

                

                    
阶段作用产物要点

                    
① 提取DWG→DXF→结构化 JSON/MDdwg-extract/**.json|md--resume 断点续跑；-w 多进程；依赖系统 dwg2dxf（libredwg）

                    
② 渲染生成图片供目视/VLMdwg-render/**.png|svg--tiles 输出瓦片+全局图+manifest 供 VLM 消费；PNG 长边受 DWG_KB_RENDER_MAX_EDGE 限制

                    
③ 双轨校验VLM 声明 vs 硬数据裁决*.verify.json四类声明 room_name/title_field/discipline/number；结构化数据永远优先；每项含 evidence

                    
④ 诊断/待审解析风险与人工复核风险统计 / 清单diagnose 看 ACAD_PROXY、未知实体、风险级；review 汇总待审项（只列不自动处理）

                    
⑤ 构建JSON → RDF + 图knowledge.trig/json、graph.html解析 callouts→references 边、块引用+连通性边；写入走文件锁，可安全并发

                    
⑥ 消费查询/服务/AI—Web UI（端口 8260）；MCP stdio；SPARQL/NL 查询均带 evidence

                

                
3. 快速上手

                
# 1) 安装（Python 3.10+；DWG 转换还需系统安装 libredwg/dwg2dxf）
pip install -e ".[all]"        # 含 ezdxf、matplotlib、mcp、neo4j 等全部可选依赖

# 2) 提取（断点续跑 + 8 进程，仅 2025 年目录）
atlisp-dwg-kb extract /path/to/dwgs --resume -w 8 --project 2025

# 3) 构建知识库（RDF + 图谱 + graph.html）
atlisp-dwg-kb build --extract-dir /path/to/dwgs/dwg-extract

# 4) 启动 API + Web UI（浏览器访问 http://<host>:8260/ui）
atlisp-dwg-kb serve --port 8260


                
Web 端「构建知识库」页签是图形化入口：选目录 → 选模式 → 开始构建，完成后自动刷新统计与图谱。


                
4. CLI 命令详解

                

                    
命令说明常用示例

                    
extractDWG→JSON/MD 元数据提取atlisp-dwg-kb extract <root> --resume --limit 50 -w 8 -o OUT

                    
render渲染 PNG/SVG（视觉轨）atlisp-dwg-kb render <file|dir> -f png --tiles --resume

                    
verify双轨校验；--eval 跑黄金用例集（准确率须 100%）atlisp-dwg-kb verify <json|dwg|dir> -o OUT -q "问题"

                    
diagnose解析风险报告（proxy/未知实体/风险级）atlisp-dwg-kb diagnose <dwg|dir|json>

                    
review待审清单（高风险/警告/冲突/低置信）atlisp-dwg-kb review [dir] --json -n 50

                    
build提取结果 → RDF + 图谱atlisp-dwg-kb build --extract-dir <dir>

                    
query / stats自然语言查询 / 统计atlisp-dwg-kb query "哪些项目用了暖通系统？"

                    
serve / all / uiAPI+UI(8260) / 同上 / 旧版 Gradio(7860)atlisp-dwg-kb serve --host 0.0.0.0 --port 8260 --no-browser

                    
mcpMCP stdio 服务器，供 AI 客户端调用atlisp-dwg-kb mcp

                    
autobuildCPU 空闲时自动提取+构建（守护）atlisp-dwg-kb autobuild <root> --cpu-threshold 30 --once

                    
serviceWindows 服务（pywin32）atlisp-dwg-kb service install <root>；start / stop / status / uninstall

                    
export-neo4j导出 Neo4j Cypheratlisp-dwg-kb export-neo4j

                    
trayWindows 系统托盘管理atlisp-dwg-kb tray <root> -b

                


                
5. Web 页面功能

                
    
                    
  • 统计概览：知识库全局统计（图纸/项目/专业/图层/块），基于已构建的 RDF。
    • 
                    
  • 智能查询：自然语言（关键词启发式，非 LLM）或 SPARQL，结果附 evidence。
    • 
                    
  • 图纸浏览：按专业筛选图纸列表（分页，每页 ≤1000）。
    • 
                    
  • 设计演进：按文件名版本模式（_t3、(1)、日期）追踪版本链。
    • 
                    
  • 跨专业关联：块引用/连通性/图号互引的关联查找、协调矩阵、共享图层。
    • 
                    
  • 图谱可视化：Sigma.js 交互图谱（拖拽/缩放），需先构建。
    • 
                    
  • 双轨校验：渲染、完整校验、待审清单；大图纸自动走后台任务轮询。
    • 
                    
  • 构建知识库：目录选择 + 四种构建模式 + 进度条/日志。
    • 
                

                
每个页签标题下的「功能介绍与使用说明」折叠块有更细的操作说明。

                
6. API 参考（主要端点）

                

                    
端点方法说明

                    
/healthGET版本 / rdf_loaded / rdf_stale / graph_built（就绪信号）

                    
/statsGET全局统计

                    
/drawings /projects /layers /blocksGET列表（discipline/project 过滤，分页 {items,total,offset,limit}，limit≤1000）

                    
/search?q=GET全文关键词搜索

                    
/queryPOST自然语言 / SPARQL 查询（含 evidence）

                    
/drawings/{id}/evolution /cross_refGET版本链 / 跨专业关联

                    
/evolution/chains /cross_ref/matrix /shared_layers /bridgesGET演进链 / 协调矩阵 / 共享图层 / 关联桥

                    
/drawings/{id}/renderPOST渲染；?background=true 异步任务

                    
/drawings/{id}/verifyPOST双轨校验；?question= 附加问题；?background=true 异步

                    
/renders/{filename}GET获取渲染图

                    
/review_queueGET待审清单

                    
/build /build/statusPOST / GET启动构建 / 查询进度（含 run_id）

                    
/jobs/{id}GET异步任务状态

                    
/graph/htmlGETSigma.js 图谱页

                    
/fs/listGET目录浏览（构建选目录用）

                    
/ui /static/*GETWeb UI 与静态资源

                

                
安全/限流默认对内网开放（启动时警告）；设置 DWG_KB_API_KEY（浏览器资源豁免）、DWG_KB_ALLOWED_ROOTS、DWG_KB_RATE_LIMIT、DWG_KB_MAX_BODY_BYTES、DWG_KB_SPARQL_MAX_CHARS/DWG_KB_SPARQL_DEFAULT_LIMIT、DWG_KB_RENDER_TIMEOUT 可加固，详见 SECURITY.md。


                
7. MCP 工具（AI 客户端）

                
启动 atlisp-dwg-kb mcp（stdio，JSON-RPC over stdout，日志走 stderr），供 Claude/Cursor 等 AI 客户端调用：

                

                    
工具说明

                    
read_dwg(path)读取图纸元数据（提取 JSON）

                    
render_dwg(path, format)渲染 PNG/SVG，返回磁盘路径（不把二进制推进 AI 上下文）

                    
diagnose_dwg(path)解析风险诊断

                    
verify_dwg(path, question)双轨校验

                    
review_queue(extract_dir, limit)待审清单

                    
query_kb(question)知识库查询

                    
search_drawings(keyword, discipline, …)按关键词/专业搜索图纸

                

                
8. 部署方式

                

                    
方式适用说明

                    
systemd（Linux）生产常驻atlisp-dwg-kb.service（autobuild）+ atlisp-dwg-kb-serve.service（API/UI，0.0.0.0:8322），见 scripts/linux/install-service.sh；两者共享 /var/lib/atlisp-dwg-kb（StateDirectory）与 /etc/default/atlisp-dwg-kb 环境文件

                    
Windows 服务Windows 常驻atlisp-dwg-kb service install|start|stop|status|uninstall（pywin32），或 NSSM + scripts/windows/install-service.ps1

                    
系统托盘Windows 桌面atlisp-dwg-kb tray <root> -b，后台空闲时自动提取+构建

                    
手动临时使用直接跑 CLI：extract → build → serve

                

                
systemd 部署统一用 /var/lib/atlisp-dwg-kb（服务内设置 DWG_KB_DATA_DIR/DWG_EXTRACT_DIR），UI 展示的正是守护进程构建的库；手动 CLI 默认用 ~/.dwg-kb，需自行 export 这两个变量对齐。


                
9. 存储位置与数据目录

                

                    
路径内容

                    
~/.dwg-kb/默认数据目录（knowledge.trig/json、graph/）；可用 DWG_KB_DATA_DIR 覆盖

                    
<root>/dwg-extract/提取结果（JSON/MD，保留源目录结构），DWG_EXTRACT_DIR 可改

                    
<root>/dwg-render/渲染输出（PNG/SVG/瓦片）

                    
~/.dwg-kb/renders/、~/.dwg-kb/verify/API 按需渲染 / DWG 输入的校验报告（不写入 raw/）

                    
raw/DWG 源档 symlink（按年份目录），只读，严禁写入/提交

                

                
全量语料库约 550 万三元组，启动时 rdflib 加载约 10 分钟 / 7.5GB（后台预加载，/health.rdf_loaded 为就绪信号；重建在后台进行，不阻塞请求）。


                
10. 主要环境变量

                

                    
变量作用

                    
DWG_KB_DATA_DIR / DWG_EXTRACT_DIR数据目录 / 提取目录

                    
DWG_KB_VLM_PROVIDER / BASE_URL / MODEL / API_KEY / TIMEOUTVLM 提供方（默认 mock 离线；openai_compat 走 OpenAI 兼容接口）

                    
DWG_KB_RENDER_MAX_EDGE / RENDER_TIMEOUTPNG 长边上限（默认 4000）/ 渲染超时（超时杀子进程返回 504）

                    
DWG_KB_TILE_SIZE / TILE_OVERLAP / VLM_MAX_TILES瓦片尺寸（1536）/ 重叠（192）/ VLM 最多消费瓦片数

                    
DWG_KB_CONN_TOL / MAX_CONNECTIONS实体连通判定容差 / 单实体最大连通数

                    
DWG_KB_API_KEY / ALLOWED_ROOTS / RATE_LIMIT / MAX_BODY_BYTESAPI 鉴权 / 目录白名单 / 限流 / 请求体上限

                    
DWG_KB_SPARQL_MAX_CHARS / SPARQL_DEFAULT_LIMITSPARQL 长度上限 / 默认行数

                    
DWG_KB_LOG_LEVEL / LOG_FORMAT日志级别 / 格式（json 用于采集）

                    
NEO4J_URI / NEO4J_USER / NEO4J_PASSWORDNeo4j 导出连接

                


                
11. 常见问题（FAQ）

                
    
                    
  • DWG 转换失败 / 提示缺少 dwg2dxf：libredwg 必须系统级安装（如 sudo apt install libredwg），仅装 Python 依赖不够。
    • 
                    
  • 渲染图中文是方块：需要系统安装 CJK 字体（Noto / 文泉驿 / 微软雅黑），程序会自动探测。
    • 
                    
  • 统计为空或查询报 RDF 未加载：全量库加载约 10 分钟，等 /health 的 rdf_loaded=true；重建时旧数据继续可用（stale-while-revalidate）。
    • 
                    
  • 图谱页显示「图谱未构建」：先运行「构建知识库」（或 CLI build），再进入图谱页。
    • 
                    
  • 大图纸渲染/校验超时：API 支持 ?background=true 异步任务（Web UI 已自动采用，轮询 /jobs/{id}）。
    • 
                    
  • 提取中断后如何续跑：加 --resume，按 dwg-extract/.processed.json 跳过已完成文件。
    • 
                    
  • 安全加固：对外暴露前设置 DWG_KB_API_KEY 等变量，详见 SECURITY.md。
    •