配置说明

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

配置来源和优先级

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

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

服务模式下，POST /api/jobs 会生成任务配置并写入：

backend/service_workspace/{job_id}/config.json

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

前端参数映射

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

前端字段	后端配置
`dataColIndex`	`DATA_COL_INDEX`
`seed`	`SEED`
`weightColIndex`	`WEIGHT_COL_INDEX`
`fontColor`	`FONT_COLOR`
`nRepetitions`	`N_REPETITIONS`
`strokeWeights=false`	`ENABLE_STROKE_WEIGHTS=false`

前端只在重复次数大于 1 时传 N_REPETITIONS，只在关闭笔画权重时传 ENABLE_STROKE_WEIGHTS=false。

常用配置

键	默认值	说明
`MODE`	`IMAGE`	掩膜模式，`IMAGE` 或 `TEXT`
`MASK_IMAGE_PATH`	`7887.png`	IMAGE 模式掩膜路径，服务模式会覆盖为上传文件路径
`IMAGE_CANVAS_MODE`	`WIDTH`	图片掩膜缩放模式
`FILL_ON`	`BLACK`	`BLACK` 表示黑色可填，`WHITE` 表示白色可填
`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`	是否在无 Excel 权重时使用笔画复杂度权重
`N_REPETITIONS`	`1`	名单重复倍率
`SIZE_RATIO`	`2.0`	`max_font` 相对 `min_font` 的比例
`PACKING_EFFICIENCY`	`0.85`	面积模型中的打包效率
`MIN_ACCEPT_FILL_RATIO`	`0.75`	填充率重试阈值
`REQUIRE_ALL_WORDS`	`True`	搜索阶段是否优先要求达到目标词数
`USER_MIN_FONT_SIZE`	`None`	用户覆盖最小字号
`USER_MAX_FONT_SIZE`	`None`	用户覆盖最大字号
`FONT_SCALE_MIN`	`0.5`	二分搜索缩放下限
`FONT_SCALE_MAX`	`1.2`	二分搜索缩放上限
`LIMIT_LARGE_FONTS`	`True`	是否限制大字号数量
`LARGE_FONT_LIMIT_RATIO`	`0.2`	大字号数量上限占比
`LARGE_FONT_THRESHOLD_RATIO`	`0.8`	超过有效最大字号该比例视为大字号
`LARGE_FONT_CAP_RATIO`	`0.6`	超过大字号限制后的降级比例
`ENABLE_DOT_MATRIX`	`False`	是否用点阵补偿空白区域
`CANVAS_RETRY_MAX_ROUNDS`	`1`	画布扩大重试轮数
`FONT_COLOR`	`#000000`	固定字体颜色；为空时使用调色板
`SEED`	`None`	随机种子
`LAYOUT_ORDER_MODE`	`SORTED`	展开序列排序模式
`LAYOUT_SEED`	`None`	布局顺序种子，默认继承 `SEED`

JSON 别名

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

别名	正式配置
`seed`	`SEED`
`layout_order_mode`	`LAYOUT_ORDER_MODE`
`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。字体不可用会直接失败。

4.2 KiB Raw Blame History