CLAUDE.md

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

项目概述

Markdown 文档向量数据库 — 将 .md 文件分块 → 嵌入 → 存入 ChromaDB，通过 FastAPI HTTP 或 CLI 提供语义检索。

常用命令

uv sync                                   # 安装依赖
uv run pytest tests/ -v                   # 全部测试 (46 个)
uv run pytest tests/test_api.py -v        # 单个测试模块
uv run pytest tests/ -v -k "test_search"  # 按名称过滤

# CLI（所有命令支持 --config/-c 指定配置文件）
uv run python -m src.cli.main ingest <file.md>
uv run python -m src.cli.main ingest-dir ./md_docs/
uv run python -m src.cli.main search "关键词" -k 5
uv run python -m src.cli.main stats
uv run python -m src.cli.main serve --port 8000

架构

core/                         # 核心逻辑（不依赖 server/cli）
├── config.py                 # YAML → dataclass, load_dotenv() 加载 .env
├── db.py                     # VectorDB: 线程安全的 ChromaDB 封装
├── embedder.py               # 策略模式: LocalEmbedder / OpenAIEmbedder / DashscopeEmbedder
├── ingest.py                 # MarkdownSplitter(混合分块) + DocumentIngestor(分批嵌入)
└── search.py                 # Searcher: 语义检索 + 源文件管理

server/                       # FastAPI HTTP 层
├── app.py                    # Depends(get_state) 依赖注入, 速率限制中间件
├── deps.py                   # AppState: 集中管理 db/embedder/searcher/ingestor
└── auth.py                   # API Key 认证 (MD_VECTOR_API_KEY) + 速率限制器

cli/main.py                   # Typer CLI，5 个命令 + --config 选项

数据流: MD 文件 → MarkdownSplitter.split() → batch_embed() → ChromaDB collection.add() → Searcher.search()

依赖方向: config ← db ← embedder ← ingest/search ← server/cli

关键实现细节

嵌入 Provider 架构 (embedder.py)

策略模式，接口 Embedder(Protocol):

Provider	类	API 格式	默认模型
`local`	`LocalEmbedder`	sentence-transformers	BAAI/bge-small-zh-v1.5
`openai`	`OpenAIEmbedder`	OpenAI 兼容	text-embedding-3-small
`dashscope`	`DashscopeEmbedder`	阿里云自定义 HTTP	text-embedding-v4

config.api_base / config.model 可覆盖默认值。batch_embed() 分批嵌入（每批 32 条）防 OOM。本地模型未缓存时自动通过 hf-mirror.com 下载。

线程安全 (db.py + ingest.py + search.py)

VectorDB._write_lock (threading.Lock) 保护所有写操作（collection.add / delete / get+delete）。

认证与安全 (auth.py + app.py)

API Key: 环境变量 MD_VECTOR_API_KEY → verify_api_key 依赖注入到 ingest/search/delete 端点；未设置则跳过
速率限制: RateLimiter 中间件，默认 60s 窗口内最多 30 请求
路径遍历防护: _is_safe_path() 拒绝绝对路径和 .. 穿越
错误信息: 500 返回通用消息，详细错误记入 logger.exception

配置系统 (config.py)

config.py 顶部 load_dotenv() 自动加载 .env。EMBED_API_KEY 从环境变量读取。DEFAULT_CONFIG_PATH = "config.yaml" 统一引用。

服务层 (deps.py + app.py)

AppState 类集中管理 db/embedder/searcher/ingestor 单例。端点通过 FastAPI Depends(get_state) 获取，可测试、可替换。is_healthy() 真实验证 ChromaDB 和 Embedder 可用性。

配置

config.yaml + .env 联合控制。复制 .env.example 为 .env 填入密钥。

HTTP API

方法	路径	认证	说明
GET	`/`	-	重定向到 /docs
GET	`/api/v1/health`	-	真实健康检查 (ChromaDB + Embedder)
GET	`/api/v1/collections`	-	集合和源文件列表
POST	`/api/v1/ingest`	API Key	入库 (file_path 或 content+file_name)
POST	`/api/v1/search`	API Key	语义检索 (query + top_k 1-100)
DELETE	`/api/v1/documents/{file_name}`	API Key	按文件名删除

4.1 KiB Raw Blame History Unescape Escape