CLAUDE.md

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

项目概述

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

常用命令

环境安装

# 创建虚拟环境
uv venv

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

运行脚本

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

项目架构

目录结构

src/app/
├── config/           # 配置与客户端初始化
│   ├── setting.py    # .env 配置加载（MinIO/Milvus/MySQL/Embedding）
│   ├── minio_client.py   # MinIO 客户端（单例）
│   ├── milvus_client.py  # Milvus 客户端（LRU缓存）
│   ├── embeddings.py     # OpenAI Embeddings 客户端
│   └── database.py       # SQLAlchemy 异步引擎
├── models/           # 数据库模型
│   └── standard_base_info.py  # 施工标准规范表模型
└── scripts/          # 数据处理脚本
    ├── base_*        # 编制依据处理流程
    └── plan_*        # 施工方案处理流程

配置管理

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

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

数据处理流程

编制依据 (base_* 系列)：

base_count.py → 检查 Excel ID 与目录匹配
base_check.py → 校验目录结构/命名一致性
base_info_json_generation.py → 生成 JSON（含 MD 切分 parent/children）
base_in_minio.py → 上传文件到 MinIO
base_info_in_database.py → 写入 MySQL
base_create_collection.py → 创建 Milvus Collection（含 BM25 function）
base_in_collection.py → 向量化并写入 Milvus

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

Markdown 切分逻辑

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

parent：按 # 一级标题切分，超长段（>6000字符）再切片，共享 parent_id
children：在 parent 内按空行切分，记录 hierarchy（标题路径）
parent_id：由 doc_name|parent_seq|h1_title SHA1 生成，保证稳定

Milvus Collection Schema

Collection 包含以下字段：

字段	类型	说明
`text`	VARCHAR(65535)	文本内容，enable_analyzer=True
`dense`	FLOAT_VECTOR	密集向量（语义检索）
`sparse`	SPARSE_FLOAT_VECTOR	稀疏向量（BM25 函数生成）
`document_id`	VARCHAR(256)	文档 ID
`parent_id`	VARCHAR(256)	父节点 ID
`metadata`	JSON	元数据（chinese_name, standard_number 等）

BM25 函数配置：

schema.add_function(
    Function(
        name="bm25_fn",
        input_field_names=["text"],
        output_field_names=["sparse"],
        function_type=FunctionType.BM25,
    )
)

开发注意事项

脚本路径配置：大多数脚本顶部有 EXCEL_FILE、ROOT_FOLDER 等路径常量，运行前需改为本地路径
base/plan 区分：base_* 与 plan_* 脚本对应不同数据类型，Collection 名不同，不要混用
Milvus 动态字段：当前 schema 未开启动态字段，写入字段必须与 collection 定义完全一致
向量维度：默认 4096 维，由 EMBEDDING_MODEL（Qwen3-Embedding-8B）决定

CLAUDE.md 3.8 KB Histórico Raw