配置参考

本页汇总 Services 模块涉及的核心配置项。

配置来源

服务统一从全局 config（pydantic-settings）读取配置，优先级如下：

环境变量（最高）
.env 文件
代码默认值（最低）

ChunkingService 配置

通用配置

参数	类型	默认值	说明	环境变量
`chunking.size`	int	512	默认分块字符数	`CHUNK_SIZE`
`chunking.overlap`	int	50	默认重叠字符数	`CHUNK_OVERLAP`
`chunking.default_strategy`	str	`fixed_size`	默认分块策略	`CHUNK_DEFAULT_STRATEGY`

句子策略配置

参数	类型	默认值	说明	环境变量
`chunking.sentence_target_size`	int	512	目标块大小	`CHUNK_SENTENCE_TARGET_SIZE`
`chunking.sentence_max_per_chunk`	int	10	每块最大句子数	`CHUNK_SENTENCE_MAX_PER_CHUNK`

段落策略配置

参数	类型	默认值	说明	环境变量
`chunking.paragraph_target_size`	int	1024	目标块大小	`CHUNK_PARAGRAPH_TARGET_SIZE`
`chunking.paragraph_max_per_chunk`	int	5	每块最大段落数	`CHUNK_PARAGRAPH_MAX_PER_CHUNK`

语义策略配置

参数	类型	默认值	说明	环境变量
`chunking.semantic_similarity_threshold`	float	0.7	相似度阈值	`CHUNK_SEMANTIC_SIMILARITY_THRESHOLD`
`chunking.semantic_min_chunk_size`	int	200	最小块大小	`CHUNK_SEMANTIC_MIN_CHUNK_SIZE`
`chunking.semantic_max_chunk_size`	int	1000	最大块大小	`CHUNK_SEMANTIC_MAX_CHUNK_SIZE`

示例：

# .env
CHUNK_SIZE=512
CHUNK_OVERLAP=50
CHUNK_DEFAULT_STRATEGY=recursive

# 句子策略
CHUNK_SENTENCE_TARGET_SIZE=512
CHUNK_SENTENCE_MAX_PER_CHUNK=10

# 段落策略
CHUNK_PARAGRAPH_TARGET_SIZE=1024
CHUNK_PARAGRAPH_MAX_PER_CHUNK=5

使用：

from ai_service.utils.settings import config

print(f"Chunk size: {config.chunking.size}")
print(f"Overlap: {config.chunking.overlap}")
print(f"Default strategy: {config.chunking.default_strategy}")

EmbeddingService 配置

参数	类型	默认值	说明	环境变量
`embedding.backend_type`	str	`api`	嵌入后端类型（`api` / `local`）	`EMBEDDING_BACKEND_TYPE`
`embedding.provider`	str	`sentence_transformers`	嵌入提供商（`sentence_transformers` / `dashscope`）	`EMBEDDING_PROVIDER`
`embedding.model`	str	`sentence-transformers/all-MiniLM-L6-v2`	嵌入模型名称	`EMBEDDING_MODEL`
`embedding.dim`	int	384	向量维度	`EMBEDDING_DIM`
`embedding.model_dir`	str	`resources/models`	本地模型目录	`EMBEDDING_MODEL_DIR`
`embedding.offline_mode`	bool	True	仅使用本地缓存	`EMBEDDING_OFFLINE_MODE`

在线（DashScope）示例

EMBEDDING_BACKEND_TYPE=api
EMBEDDING_PROVIDER=dashscope
EMBEDDING_MODEL=text-embedding-v4
EMBEDDING_DIM=1536
EMBEDDING_OFFLINE_MODE=false
# 必填
DASHSCOPE_API_KEY=your_api_key

本地（SentenceTransformers）示例

EMBEDDING_BACKEND_TYPE=local
EMBEDDING_PROVIDER=sentence_transformers
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_DIM=384
EMBEDDING_OFFLINE_MODE=true
EMBEDDING_MODEL_DIR=resources/models

注意：qwen3-rerank 属于 rerank_models，不能配置到 embedding.model。

Rerank 配置

参数	类型	默认值	说明	环境变量
`rerank.enabled`	bool	false	是否启用重排阶段	`RERANK_ENABLED`
`rerank.provider`	str	`dashscope`	重排提供商	`RERANK_PROVIDER`
`rerank.model`	str	`qwen3-rerank`	重排模型（类别必须为 `rerank_models`）	`RERANK_MODEL`
`rerank.top_k`	int	20	进入重排阶段的候选上限	`RERANK_TOP_K`

示例：

RERANK_ENABLED=true
RERANK_PROVIDER=dashscope
RERANK_MODEL=qwen3-rerank
RERANK_TOP_K=20

超时配置

参数	类型	默认值	说明	环境变量
`timeouts.embedding_model_load_seconds`	int	300	模型加载超时	`TIMEOUT_EMBEDDING_MODEL_LOAD_SECONDS`
`timeouts.ingestion_document_seconds`	int	600	单文档处理超时	`TIMEOUT_INGESTION_DOCUMENT_SECONDS`
`timeouts.ingestion_job_seconds`	int	3600	任务整体超时	`TIMEOUT_INGESTION_JOB_SECONDS`

示例：

TIMEOUT_EMBEDDING_MODEL_LOAD_SECONDS=600
TIMEOUT_INGESTION_DOCUMENT_SECONDS=900
TIMEOUT_INGESTION_JOB_SECONDS=7200

存储相关配置

PostgreSQL

参数	环境变量
数据库连接	`DATABASE_URL`
连接池大小	`DB_POOL_SIZE`

Qdrant

参数	默认值	环境变量
Host	`localhost`	`QDRANT_HOST`
Port	`6333`	`QDRANT_PORT`
集合基础名称	`document_vectors`	`QDRANT_COLLECTION_NAME`
指纹集合命名开关	`true`	`QDRANT_USE_EMBEDDING_FINGERPRINT_COLLECTION`
灰度双读开关	`false`	`QDRANT_DUAL_READ_ENABLED`
双读 fallback 列表	`[]`	`QDRANT_READ_FALLBACK_COLLECTION_NAMES`

当开启指纹命名时，写入集合名类似：

document_vectors__text-embedding-v4__1536

用于避免不同 embedding 维度（例如 384/1536）混写。

MinIO

参数	环境变量
Endpoint	`MINIO_ENDPOINT`
Access Key	`MINIO_ACCESS_KEY`
Secret Key	`MINIO_SECRET_KEY`
Bucket	`MINIO_BUCKET_NAME`

配置优先级

环境变量
.env
默认值

性能调优建议

分块调优

# 更小的块（高精度检索）
CHUNK_SIZE=256
CHUNK_OVERLAP=30
CHUNK_DEFAULT_STRATEGY=sentence

# 中块（平衡）
CHUNK_SIZE=512
CHUNK_OVERLAP=50
CHUNK_DEFAULT_STRATEGY=recursive

# 更大的块（完整上下文）
CHUNK_SIZE=1024
CHUNK_OVERLAP=100
CHUNK_DEFAULT_STRATEGY=paragraph

嵌入调优

# 在线高质量（推荐）
EMBEDDING_PROVIDER=dashscope
EMBEDDING_MODEL=text-embedding-v4
EMBEDDING_DIM=1536

# 离线快速
EMBEDDING_PROVIDER=sentence_transformers
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_DIM=384

超时调优

# 大文档场景
TIMEOUT_INGESTION_DOCUMENT_SECONDS=1200
TIMEOUT_INGESTION_JOB_SECONDS=7200

# 小文档场景
TIMEOUT_INGESTION_DOCUMENT_SECONDS=300
TIMEOUT_INGESTION_JOB_SECONDS=1800

环境示例

开发环境

CHUNK_SIZE=512
CHUNK_OVERLAP=50
CHUNK_DEFAULT_STRATEGY=recursive
EMBEDDING_PROVIDER=dashscope
EMBEDDING_MODEL=text-embedding-v4
EMBEDDING_DIM=1536
EMBEDDING_OFFLINE_MODE=false
RERANK_ENABLED=true
RERANK_MODEL=qwen3-rerank
TIMEOUT_EMBEDDING_MODEL_LOAD_SECONDS=300
TIMEOUT_INGESTION_DOCUMENT_SECONDS=600

生产环境

CHUNK_SIZE=512
CHUNK_OVERLAP=50
CHUNK_DEFAULT_STRATEGY=recursive
EMBEDDING_PROVIDER=dashscope
EMBEDDING_MODEL=text-embedding-v4
EMBEDDING_DIM=1536
EMBEDDING_OFFLINE_MODE=false
RERANK_ENABLED=true
RERANK_MODEL=qwen3-rerank
TIMEOUT_EMBEDDING_MODEL_LOAD_SECONDS=600
TIMEOUT_INGESTION_DOCUMENT_SECONDS=900
TIMEOUT_INGESTION_JOB_SECONDS=7200

测试环境

CHUNK_SIZE=256
CHUNK_OVERLAP=30
CHUNK_DEFAULT_STRATEGY=fixed_size
EMBEDDING_PROVIDER=sentence_transformers
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_DIM=384
EMBEDDING_OFFLINE_MODE=true
RERANK_ENABLED=false
TIMEOUT_EMBEDDING_MODEL_LOAD_SECONDS=60
TIMEOUT_INGESTION_DOCUMENT_SECONDS=120

策略特定环境配置

适合新闻/文章

CHUNK_DEFAULT_STRATEGY=sentence
CHUNK_SENTENCE_TARGET_SIZE=512
CHUNK_SENTENCE_MAX_PER_CHUNK=8

适合技术文档

CHUNK_DEFAULT_STRATEGY=paragraph
CHUNK_PARAGRAPH_TARGET_SIZE=1024
CHUNK_PARAGRAPH_MAX_PER_CHUNK=3

适合代码文件

CHUNK_DEFAULT_STRATEGY=recursive
CHUNK_SIZE=512
CHUNK_OVERLAP=50

配置校验

配置会在启动时校验，不合法会抛出 ValidationError：

from ai_service.utils.settings import config
print(config.chunking.size)
print(config.chunking.default_strategy)