CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

路桥数据治理与知识库入库脚本项目，用于将标准规范、施工方案等文档向量化并存入 Milvus/MinIO/MySQL。

核心数据类型：

base_*：编制依据（标准规范）
plan_*：施工方案
status_*：时效性状态
entity_*：实体抽取

常用命令

环境安装

# 创建虚拟环境（默认在项目根目录 .venv）
uv venv

# 安装依赖（使用清华镜像）
uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple

虚拟环境

项目使用 uv 管理依赖，虚拟环境位于 .venv/。

激活虚拟环境：

# Windows PowerShell
.venv\Scripts\Activate.ps1

# Windows CMD
.venv\Scripts\activate.bat

# Linux/macOS
source .venv/bin/activate

运行方式：

推荐：直接使用 uv run（自动在虚拟环境中执行）
```
uv run -m src.app.scripts.base_info_json_generation
```

或：激活虚拟环境后直接运行

# 先激活虚拟环境
# 再运行脚本

运行脚本

# 运行任意脚本（示例）
uv run -m src.app.scripts.base_info_json_generation
uv run -m src.app.scripts.base_in_collection
uv run -m src.app.scripts.status_excel_info_json

重要：多数脚本是"一次性批处理"，路径参数（EXCEL_FILE、ROOT_FOLDER 等）直接写在脚本顶部，运行前需改为本地路径。

项目架构

目录结构

src/app/
├── config/           # 配置与客户端初始化
│   ├── setting.py    # .env 配置加载（MinIO/Milvus/MySQL/Embedding）
│   ├── minio_client.py   # MinIO 客户端（单例）
│   ├── milvus_client.py  # Milvus 客户端（LRU缓存）
│   ├── embeddings.py     # MetaXEmbeddings（requests-based，非 OpenAI）
│   └── database.py       # SQLAlchemy 异步引擎
├── models/           # 数据库模型
│   └── standard_base_info.py  # 施工标准规范表模型
└── scripts/          # 数据处理脚本
    ├── base_*        # 编制依据处理流程
    ├── plan_*        # 施工方案处理流程
    ├── status_*      # 时效性状态处理
    ├── entity_*      # 实体抽取与入库
    └── tool/         # 辅助工具（时效性查询、去重等）

配置管理

所有服务配置通过 .env 文件管理，由 setting.py 的 Settings 类加载：

服务	关键配置项
MinIO	`MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, `MINIO_BUCKET_NAME`
Milvus	`MILVUS_HOST`, `MILVUS_PORT`, `MILVUS_DB`, `MILVUS_USER`, `MILVUS_PASSWORD`
MySQL	`DATABASE_URL` (async: `mysql+aiomysql://...`)
Embedding	`EMBEDDING_BASE_URL`, `EMBEDDING_MODEL`, `EMBEDDING_API_KEY`

数据处理流程

编制依据 (base_* 系列)：

base_count.py → Excel 与目录编号对比
base_check.py → 目录结构/命名校验
base_info_json_generation.py → 生成 JSON（含 MD 切分 parent/children）
base_in_minio.py → 上传文件到 MinIO
base_info_in_database.py → 写入 MySQL
base_collections_create.py → 创建 Milvus Collection（含 BM25 + 中文分词）
base_in_collection.py → 向量化并写入 Milvus

施工方案 (plan_* 系列)：流程同上，Collection 名不同（t_rag_kng_construction_plan_*）。

时效性状态 (status_* 系列)：Excel → JSON → MySQL → Milvus 状态检索集合。

实体 (entity_* 系列)：从文档抽取实体并向量化导入 Milvus 实体集合。

Markdown 切分逻辑

文档切分在 base_info_json_generation.py 中实现：

parent：按 # 一级标题切分，超长段（>6000字符）再切片，共享 parent_id
children：按中文句号 。 切分，保留标题上下文，标题本身不生成子表记录
parent_id：由 doc_name|parent_seq|h1_title SHA1 生成，保证稳定
Markdown 表格：整体保留，不按句号切分（避免破坏表结构）
HTML 表格：自动转换为 Markdown 表格格式

Milvus Collection Schema

Collection（父表/子表结构相同）包含以下字段：

字段	类型	说明
`pk`	INT64	主键，auto_id
`text`	VARCHAR(65535)	文本内容，enable_analyzer=True, analyzer_params={"type": "chinese"}
`dense`	FLOAT_VECTOR(4096)	密集向量（语义检索）
`sparse`	SPARSE_FLOAT_VECTOR	稀疏向量（BM25 函数生成）
`document_id`	VARCHAR(128)	文档 ID
`parent_id`	VARCHAR(128)	父节点 ID
`index`	INT64	索引序号
`tag_list`	VARCHAR(2048)	标签
`permission`	JSON	权限
`metadata`	JSON	元数据（chinese_name, standard_number, file_url 等）
`is_deleted`	BOOL	删除标志
`created_by/updated_by`	VARCHAR(128)	创建人/修改人
`created_time/updated_time`	INT64	创建/修改时间戳

BM25 + 中文分词配置（创建 Collection 时必须）：

schema.add_field(
    "text",
    DataType.VARCHAR,
    max_length=65535,
    enable_analyzer=True,
    analyzer_params={"type": "chinese"},  # 关键：中文分词
)
schema.add_function(
    Function(
        name="bm25_fn",
        input_field_names=["text"],
        output_field_names=["sparse"],
        function_type=FunctionType.BM25,
    )
)

入库脚本运行时特性

base_in_collection.py / plan_info_in_collection.py 具有以下特性：

分批插入：避免 GRPC 64MB 消息大小限制（默认 50 行/批）
重试机制：失败自动重试 3 次，递增延迟
断点续传：Ctrl+C 暂停时保存进度到 JSON，下次运行可恢复
VARCHAR 保护：超长文本按 UTF-8 字节切分，不截断丢弃
Embedding token 保护：文本切分同时满足 Milvus VARCHAR(65535) 和 embedding 输入限制（约 12KB）
幂等写入：每个文档先按 document_id 清理旧数据再写入

开发注意事项

脚本路径配置：多数脚本顶部有 EXCEL_FILE、ROOT_FOLDER 等路径常量，运行前需改为本地路径
base/plan 区分：base_* 与 plan_* 脚本对应不同数据类型，Collection 名不同，不要混用
中文分词器：创建 Milvus Collection 时必须配置 analyzer_params={"type": "chinese"}，否则 BM25 检索效果差
向量维度：默认 4096 维，由 EMBEDDING_MODEL（通常是 Qwen3-Embedding-8B）决定
Embedding 客户端：使用 MetaXEmbeddings（embeddings.py），基于 requests，非 langchain-openai
Embedding 批量请求：默认 max_batch_size=16，有重试机制
创建 Collection：使用 base_collections_create.py / t_kngs_construction_plan_collections_create.py，确保 schema 正确

常见问题

脚本报路径不存在：检查脚本顶部路径常量是否为本地真实路径
Milvus 插入失败/字段不匹配：确认 Collection schema 与写入字段一致；必要时先执行 *_collections_create.py 重建集合
Embedding 报 context length 超限：入库脚本已内置文本切分保护（约 12KB），检查是否使用正确脚本版本
BM25 搜索效果差：确认 Collection 创建时配置了中文分词器

CLAUDE.md 7.3 KB تاريخچه خام