wordcloud/docs/CONFIG.md

配置说明

本文档只覆盖当前代码中实际可用的配置。完整键集合以 backend/core/config.py 的 KNOWN_CONFIG_KEYS 为准。

配置来源和优先级

CLI 入口 backend/wordcloud_generate_hybrid.py 的顺序：

1. 加载 backend/core/config.py 默认值
2. 如果传 --config，调用 apply_json_config()
3. 调用 apply_cli_overrides()
4. 调用 finalize_runtime_config() 派生路径、字体、输出路径
5. 调用 set_random_seed()

服务模式下，POST /api/jobs 收到的 params JSON 会由服务层合并到任务配置，写入：

backend/service_workspace/{job_id}/config.json

之后由子进程通过 --config 读取。

前端参数映射

当前前端 TestWorkbench.tsx 提交的关键字段：

前端字段	后端配置
seed	SEED
dataColIndex	DATA_COL_INDEX
weightColIndex	WEIGHT_COL_INDEX
fontColor	FONT_COLOR
nRepetitions	N_REPETITIONS
strokeWeights	ENABLE_STROKE_WEIGHTS
sizeRatio	SIZE_RATIO
packingEfficiency	PACKING_EFFICIENCY
verticalRatio	VERTICAL_RATIO
targetFillRatio	TARGET_FILL_RATIO
userMinFontSize	USER_MIN_FONT_SIZE
userMaxFontSize	USER_MAX_FONT_SIZE
minReadableHeightPx	MIN_READABLE_HEIGHT_PX
workScale	WORK_SCALE
fillOn	FILL_ON
canvasRetryMaxRounds	CANVAS_RETRY_MAX_ROUNDS
canvasRetryGrowth	CANVAS_RETRY_GROWTH
layoutSeed	LAYOUT_SEED

"名单完整性"不是可关闭参数，始终是硬约束。

完整配置清单

掩膜与画布

键	默认值	说明
MODE	IMAGE	IMAGE 或 TEXT
MASK_IMAGE_PATH	7887.png	IMAGE 模式掩膜路径；服务模式会被上传文件路径覆盖
IMAGE_CANVAS_MODE	WIDTH	图片掩膜缩放模式：WIDTH / HEIGHT / AUTO
FILL_ON	BLACK	BLACK = 黑色可填，WHITE = 白色可填
FILL_CORNERS	False	是否自动填充四角区域
CORNER_FILL_RATIO	0.15	四角填充面积占画布比例
BASE_HD_WIDTH	4000	默认高清画布宽
BASE_HD_HEIGHT	4000	默认高清画布高
MIN_READABLE_HEIGHT_PX	22	最小可读高度（像素）
WORK_SCALE	0.18	高清画布到运算网格的缩放比例
CANVAS_RETRY_MAX_ROUNDS	1	画布扩大重试轮数
CANVAS_RETRY_GROWTH	1.12	完整名单放不下时的整画布边长增长比例

文本掩膜（TEXT 模式）

键	默认值	说明
MASK_TEXT	A	用作掩膜的文本
MASK_FONT_PATH	项目默认字体	掩膜字体
MASK_FONT_SIZE	3000	掩膜文字字号

数据与权重

键	默认值	说明
EXCEL_PATH	四个方向汇总录取名单.xlsx	Excel 路径；服务模式被上传文件覆盖
DATA_COL_INDEX	1	名单列，0-based
WEIGHT_COL_INDEX	None	权重列，0-based
WEIGHT_COL_NAME	None	权重列名，优先于列索引
REMOVE_DUPLICATES	False	是否对名单去重
ENABLE_STROKE_WEIGHTS	True	是否使用笔画复杂度权重

填充策略

键	默认值	说明
N_REPETITIONS	1	名单重复倍率
TARGET_FILL_RATIO	0.45	面积模型目标笔画填充率
SIZE_RATIO	2.0	max_font 相对 min_font 的比例；1.0 为等字号模式
PACKING_EFFICIENCY	0.9	面积模型中的打包效率
VERTICAL_RATIO	0.18	竖排概率，逐词独立抽取；0.0 全部横排，1.0 全部竖排

字号硬约束

键	默认值	说明
USER_MIN_FONT_SIZE	None	用户覆盖最小字号
USER_MAX_FONT_SIZE	None	用户覆盖最大字号
MIN_FONT_FLOOR	2	绝对字号下限

字体与配色

键	默认值	说明
WC_FONT_PATH	项目默认字体	布局字体
FONT_FALLBACK_PATHS	系统字体列表	字体回退路径
FONT_COLOR	#000000	固定字体颜色；为空时使用调色板
DARK_COLOR_PALETTE	5 色深色	FILL_ON=WHITE 时使用
LIGHT_COLOR_PALETTE	5 色浅色	FILL_ON=BLACK 时使用

输出

键	默认值	说明
OUTPUT_DIR	.	输出目录
OUTPUT_PREFIX	""	输出文件前缀
OUTPUT_PNG	Efficient_Result_HD_AutoResize.png	PNG 文件名
OUTPUT_SVG	Efficient_Result_HD_AutoResize.svg	SVG 文件名
DB_PATH	wordcloud_hd.db	SQLite 数据库文件名
METRICS_FILE	metrics.json	指标文件名
SAVE_DEBUG_IMAGES	False	是否保存调试图
DEBUG_OUTPUT_DIR	output	调试文件目录

可复现性

键	默认值	说明
SEED	None	随机种子
LAYOUT_SEED	None	布局顺序种子，默认继承 SEED

JSON 别名

apply_json_config() 支持部分小写别名：

别名	正式配置
seed	SEED
layout_seed	LAYOUT_SEED
excel_path	EXCEL_PATH
mask_image_path	MASK_IMAGE_PATH
output_dir	OUTPUT_DIR
output_prefix	OUTPUT_PREFIX
mode	MODE
work_scale	WORK_SCALE
weight_col_index	WEIGHT_COL_INDEX
weight_col_name	WEIGHT_COL_NAME
min_font_size	USER_MIN_FONT_SIZE
max_font_size	USER_MAX_FONT_SIZE
font_color	FONT_COLOR
stroke_weights	ENABLE_STROKE_WEIGHTS

CLI 覆盖只支持 parse_args() 中定义的参数，不支持 font_color 或 stroke_weights CLI 参数。

类型校验

CRITICAL_TYPE_CHECKS 中的配置类型错误会直接退出。未知配置键只告警，不会失败。

路径规则

• 相对路径以 backend 目录作为基准解析
• 输出路径会在 finalize_runtime_config() 中自动创建目录
• 字体先尝试项目字体，再尝试 FONT_FALLBACK_PATHS
• 字体不可用会直接失败并退出