spring.ai.transformers.embedding.model-path配置无效？

Question

在 Spring AI 1.0.x 版本中，`spring.ai.transformers.embedding.model-path` 配置项常被误认为可直接加载本地 Hugging Face 模型（如 `BAAI/bge-small-zh-v1.5`），但实际无效——原因在于该属性**仅在使用 `TransformersEmbeddingClient` 且显式禁用自动下载时才生效**，而默认配置下 Spring AI 优先通过 `model-id` 走 Hugging Face Hub 在线拉取。若本地路径存在但未设置 `spring.ai.transformers.embedding.local-model-enabled=true`，或路径格式不规范（如含空格、相对路径未解析为绝对路径、缺少 `config.json`/`pytorch_model.bin` 等必要文件），均会导致静默回退至远程模型或启动失败。此外，该属性在 `spring-ai-transformers-spring-boot-starter` 1.0.0-M3 及之前版本存在属性绑定缺陷，需升级至 M4+ 并配合 `@ConditionalOnProperty("spring.ai.transformers.embedding.local-model-enabled")` 才能正确注入。建议通过日志开启 `DEBUG` 级别 `org.springframework.ai.transformers` 包验证实际加载路径。

Answer 1

```html

一、现象层：配置项“看似可用”实则静默失效

开发者在 application.yml 中配置：

spring:
  ai:
    transformers:
      embedding:
        model-id: BAAI/bge-small-zh-v1.5
        model-path: /opt/models/bge-small-zh-v1.5

期望加载本地模型，但应用启动后仍从 Hugging Face Hub 下载远程模型——无报错、无警告、无日志提示，仅通过网络请求监控或磁盘 I/O 可间接察觉异常。

二、机制层：配置生效的三重前提条件

• ✅ 必须显式启用本地模式：spring.ai.transformers.embedding.local-model-enabled=true
• ✅ 必须使用 TransformersEmbeddingClient（而非 TransformersChatClient 或自动装配的通用 Bean）
• ✅ 必须禁用自动下载逻辑：spring.ai.transformers.embedding.download-enabled=false（Spring AI 1.0.x 默认为 true）

三、路径层：本地模型目录的合规性校验清单

检查项	合规示例	典型错误
config.json	存在且含 model_type, hidden_size	缺失或 JSON 解析失败（如 BOM 头、编码错误）
pytorch_model.bin 或 model.safetensors	文件大小 > 50MB，SHA256 匹配 HF 官方发布	空文件、符号链接未解析、权限拒绝（java.io.IOException: Permission denied）
路径格式	/absolute/path/with/no/zh%20space	相对路径（./models/...）、含 URL 编码空格（%20）、Windows 驱动器盘符未转义（C:\models → 需双反斜杠或正斜杠）

四、版本层：M3→M4 的关键修复与注入契约变更

在 spring-ai-transformers-spring-boot-starter:1.0.0-M3 中：

• @ConfigurationProperties("spring.ai.transformers.embedding") 未正确绑定 model-path 字段（字段名映射失败）
• TransformersEmbeddingOptions 构造时忽略 localModelEnabled 状态，直接 fallback 到远程

升级至 M4+ 后，核心变更包括：

@ConditionalOnProperty("spring.ai.transformers.embedding.local-model-enabled")
@Bean
public TransformersEmbeddingClient embeddingClient(...) { ... }

五、诊断层：DEBUG 日志驱动的根因定位流程

graph TD
  A[启动应用] --> B{设置 logging.level.org.springframework.ai.transformers=DEBUG}
  B --> C[观察日志流]
  C --> D["org.springframework.ai.transformers.EmbeddingModelFactory - Loading model from: file:///opt/models/bge-small-zh-v1.5"]
  C --> E["org.springframework.ai.transformers.EmbeddingModelFactory - Fallback to HF Hub: BAAI/bge-small-zh-v1.5"]
  D --> F[确认路径解析为绝对 URI，且文件系统可读]
  E --> G[检查 local-model-enabled 是否为 true，download-enabled 是否为 false]

六、实践层：生产就绪的本地模型加载模板

完整 application.yml 示例（Spring Boot 3.3 + Spring AI 1.0.0-M5）：

spring:
  ai:
    transformers:
      embedding:
        model-id: BAAI/bge-small-zh-v1.5
        model-path: /opt/models/bge-small-zh-v1.5
        local-model-enabled: true
        download-enabled: false
        device: cpu  # 显式指定避免 CUDA 初始化失败
logging:
  level:
    org.springframework.ai.transformers: DEBUG

配合 Shell 脚本验证模型完整性：

ls -l /opt/models/bge-small-zh-v1.5/{config.json,pytorch_model.bin,model.safetensors} 2>/dev/null || echo "❌ Critical files missing"

七、架构层：Spring AI 的模型加载策略决策树

框架内部加载逻辑本质是策略模式组合：

• 策略1（远程优先）：当 local-model-enabled=false 或未配置 → 走 HuggingFaceModelDownloader
• 策略2（本地强制）：当 local-model-enabled=true && download-enabled=false → 走 LocalModelLoader，并校验 model-path 下文件元数据
• 策略3（混合兜底）：当本地路径存在但模型不兼容（如 tokenizer 不匹配）→ 抛出 IllegalArgumentException 并终止启动（非静默）

八、演进层：未来版本的兼容性预告

Spring AI 1.1.0（规划中）将引入：

• spring.ai.transformers.embedding.model-source: local | hub | huggingface-cache 枚举配置，替代布尔开关
• 自动路径标准化：支持 ~/.cache/huggingface/transformers/BAAI___bge-small-zh-v1.5 符号链接解析
• 嵌入式健康检查端点：GET /actuator/ai-transformers/embedding 返回当前模型来源、SHA256、加载耗时

```