PhotoPrism Vision Schema 参考：标签响应的 JSON Schema 与 JSON 样例设计指南

后端前端图像处理人工智能AI 应用【免费下载链接】photoprismAI-Powered Photos App ✨项目地址https://gitcode.com/gh_mirrors/ph/photoprism点击查看免费下载PhotoPrism 的internal/ai/vision/schema包为外部视觉引擎OpenAI Responses API 与 Ollama 兼容模型定义了规范化的标签响应规格是整个AI 打标流程GenerateLabels→LabelResult→classify.Label的契约层。本文围绕该包的LabelsJsonSchema(nsfw)与LabelsJson(nsfw)两个核心帮助函数详解字段定义、OpenAI 与 Ollama 两种校验风格的差异、vision.yml接入方式以及响应落地后的归一化normalizeLabelResult处理链路帮助你在自建 PhotoPrism 实例上稳定接入 GPT‑vision 与本地 Ollama 打标模型。包定位所有引擎共用的标签契约层schema包位于 internal/ai/vision/schema只做一件事对外部视觉引擎返回的标签结构做统一约束。它对外只暴露两个帮助函数见 labels.goLabelsJsonSchema(nsfw bool) json.RawMessage— 返回针对 OpenAI Responses 请求定制的 JSONSchema文档用于服务端严格校验结构化输出LabelsJson(nsfw bool) string— 返回一段字面 JSON样例供只支持提示词约束结构的 Ollama 类模型照葫芦画瓢。两者的字段集合完全同源name、confidence、topicality以及可选的 NSFW 字段因此下游解析逻辑LabelResult定义于 api_response.go可以保持引擎无关——无论是 OpenAI、Ollama 还是内置 TensorFlow 打标最终都落到同一个 Go 结构体上。包内还提供了第三个帮助函数JsonSchemaName(schema, version)见 name.go用于为 API 请求生成 schema 名称。它先探测 schema 内容中包含的是labels还是caption关键字再拼接成photoprism_vision_类型_版本格式版本为空时默认v1。对应行为由 name_test.go 覆盖例如assert.Equal(t, photoprism_vision_labels_v1, JsonSchemaName(json.RawMessage(LabelsJsonSchemaDefault), )) assert.Equal(t, photoprism_vision_labels_v2, JsonSchemaName([]byte(labels), v2))两个帮助函数与两种校验风格帮助函数目标引擎格式校验强度适用场景LabelsJsonSchema(false)OpenAI标准标签JSON Schema Draft强OpenAI 在返回前由服务端强制字段类型与取值范围通过ApiFormatOpenAI调用 GPT‑vision 模型确保 PhotoPrism 收到结构良好的标签数组LabelsJsonSchema(true)OpenAI标签 NSFWJSON Schema Draft 额外布尔/浮点字段强同样强制校验且 NSFW 字段为必填当DetectNSFWLabels受DETECT_NSFWtrue EXPERIMENTALtrue门控或 NSFW 专用提示词生效时模型必须输出nsfw与nsfw_confidenceLabelsJson(false)Ollama标准标签纯 JSON 样例软通过提示词引导模型模仿结构运行自托管 Ollama 模型支持JSON 模式但不消费 JSON Schema 定义LabelsJson(true)Ollama标签 NSFW含 NSFW 键的纯 JSON 样例软提示词描述必需键解析后由适配器校验Ollama 提示词提及 NSFW 打分或 PhotoPrism 设置DetectNSFWLabelstrue关键技术差异OpenAI Responses API 接受 JSON SchemaLabelsJsonSchema*并通过拒绝非法响应来保证合规而 Ollama 目前只能靠提示词引导输出。因此对 Ollama 集成PhotoPrism 提供一份代表性 JSON 文档LabelsJson*供模型模仿随后在 Go 侧完成归一化与校验。引擎适配层如何调用这两个函数OpenAI 引擎的默认 Schema 模板直接透传包内定义openai/schema.go 中SchemaLabels(nsfw)即schema.LabelsJsonSchema(nsfw)并在 engine_openai.go 的SchemaTemplate中被默认调用Ollama 引擎同理ollama/schema.go 中SchemaLabels(nsfw)即schema.LabelsJson(nsfw)模型级兜底逻辑在 model.go 的SchemaTemplate()优先级为环境变量PHOTOPRISM_VISION_LABEL_SCHEMA_FILE→ 模型Schema内联值 → 模型SchemaFile文件 → 引擎默认模板 →LabelsJson(...)兜底。// 兜底分支model.go if m.schema { m.schema visionschema.LabelsJson(m.PromptContains(nsfw)) }其中PromptContains(nsfw)model.go通过拼接系统提示词与用户提示词判断是否包含nsfw字样从而自动决定返回带 NSFW 字段的变体。这解释了原文档中的建议OpenAI 模型在vision.yml中留空Schema即可引擎默认会自动调用LabelsJsonSchema(model.PromptContains(nsfw))。字段定义从 Schema 到LabelResultSchema 契约中的每个字段都能在 Go 结构体LabelResultapi_response.go中找到一一对应Schema 字段类型是否必填LabelResult对应字段说明namestring是Name描述主体的名词默认要求单词除非模型设置Normalize: phraseconfidencefloat是Confidence归一化置信度取值0–1topicalityfloat是Topicality相对相关度评分取值0–1解析后缺省时默认等于confidencensfwboolean仅 NSFW 变体必填NSFW敏感内容标记nsfw_confidencefloat仅 NSFW 变体必填NSFWConfidenceNSFW 判定的归一化概率两份 Schema 常量LabelsJsonSchemaDefault与LabelsJsonSchemaNSFW直接以内联字符串定义在 labels.go。普通变体的每个标签对象要求nameminLength: 1、confidenceminimum: 0、maximum: 1、topicality同样钳制在 0–1并设置additionalProperties: falseNSFW 变体额外要求nsfwboolean与nsfw_confidence0–1。外层对象要求labels数组必填数组默认值为[]同样禁止额外属性。对应的 JSON 样例供 Ollama 模仿为{ labels: [{ name: , confidence: 0, topicality: 0 }] }以及 NSFW 变体{ labels: [{ name: , confidence: 0, topicality: 0, nsfw: false, nsfw_confidence: 0 }] }解析后的兜底与归一化OpenAI Schema 强制类型与取值范围Ollama 提示词则提醒模型输出匹配的键。响应解析后PhotoPrism 在 Go 侧补全缺口并应用模型的Normalize模式置信度兜底Ollama 解析器在 engine_ollama.go 中对缺失Confidence的标签填入ollama.LabelConfidenceDefault 0.5常量定义于 ollama/const.goTopicality缺省时直接取Confidence值名称归一化normalizeLabelResultlabel_normalizer.go负责把模型返回的标签名规范化——查询classify.Rules词表TensorFlow 词汇、合并类别、分配优先级并按Normalize模式single-word/phrase/false决定是折叠成单词还是保留短语NSFW 后处理NSFWConfidence钳制在 0–1若NSFWtrue但缺少数值则自动补为 100%反之置信度超 1 时置 1 并置NSFWtrue阈值过滤归一化过程中同时应用置信度/相关性阈值低于阈值的标签会被丢弃Name置空最终被 labelsInternal 过滤再由LabelResult.ToClassify()转换为classify.Label落库。配置接入vision.yml中的 Schema 用法原文档的三条使用建议对应着三种接入形态1. OpenAI 模型Engine: openaiRequestFormat: openai在 vision.yml 中留空Schema字段让引擎默认调用LabelsJsonSchema(...)。若需扩展字段可通过Schema/SchemaFile覆盖但必须保留必需键name、confidence、topicality否则LabelResult解析会失败。Models: - Type: labels Name: gpt-5-mini Engine: openai Disabled: false Resolution: 720 Options: Detail: low MaxOutputTokens: 1024 ForceJson: true # 冗余但显式 Service: Uri: https://api.openai.com/v1/responses FileScheme: data Key: ${OPENAI_API_KEY}OpenAI 侧的完整行为可参考 openai/README.mdSchema 名称由schema.JsonSchemaName自动推导如photoprism_vision_labels_v1GPT‑5 系列默认Temperature0、TopP0以求确定性输出并随请求携带reasoning.effortlow便于追踪 token 用量。2. Ollama 模型Engine: ollamaRequestFormat: ollama依赖LabelsJson内置样例或通过model.SchemaInstructions()model.go把 schema 提醒直接拼进提示词。由于校验发生在响应到达之后标签模型应保持Format: json默认并设置Options.ForceJsontrue使解析更严格。Models: - Type: labels Name: qwen2.5vl:7b Engine: ollama Run: newly-indexed Resolution: 720 Format: json Options: Temperature: 0.05 Stop: [\n\n] ForceJson: true Service: Uri: ${OLLAMA_BASE_URL}/api/generate RequestFormat: ollama ResponseFormat: ollama FileScheme: base64 Think: false提示词拼接逻辑在 labels.go当model.SchemaInstructions()非空时schema 提醒会被追加到用户提示词末尾Return JSON that matches this schema:\n%s。更完整的 Ollama 调优建议见 ollama/README.md。3. 自定义引擎复用LabelsJsonSchema/LabelsJson即可与 PhotoPrism 的标签 DTO 保持兼容。新增字段时必须同时更新 Schema 与样例两个版本使 OpenAI 与 Ollama 适配器保持对齐。此外PHOTOPRISM_VISION_LABEL_SCHEMA_FILE环境变量提供全局覆盖优先级最高适用于想对所有 Ollama 标签模型统一替换 Schema 的场景。NSFW 变体的激活条件NSFW 字段并不是永远启用的。包级全局变量DetectNSFWLabelsconfig.go由config.go设置为DetectNSFW() Experimental()即必须同时满足PHOTOPRISM_DETECT_NSFWtrue和PHOTOPRISM_EXPERIMENTALtrue详见 internal/ai/vision/README.md。只有在该全局为真时OpenAI/Ollama 引擎的UserPrompt才会切换为 NSFW 提示词LabelPromptNSFWSchema 才会要求nsfwnsfw_confidence必填否则标签提示词保持LabelPromptDefaultlabels.IsNSFW()也不会被触发。验证与排障单元测试go test ./internal/ai/vision/schema ./internal/ai/vision -run Schema -count1Schema 命名与 NSFW 行为分别由 name_test.go 与 api_response_test.go 覆盖CLI 冒烟测试photoprism vision run -m labels --count 1 --force配合PHOTOPRISM_LOG_LEVELtrace检查清洗后的请求/响应配置校验photoprism vision ls --json可确认环境变量展开后的 schema 与模型取值无需实际发起调用常见坑Ollama 引擎下若ForceJson未开启模型可能返回非 JSON 文本导致解析失败OpenAI 引擎下自定义 Schema 若删除了必需键LabelResult反序列化会得到空标签数组。小结schema包用同一套字段、两种载体的策略解决了多引擎打标的契约一致性问题对 OpenAI 用 JSON Schema 做服务端强校验对 Ollama 用 JSON 样例加提示词做软约束最终统一归一到LabelResult再经normalizeLabelResult完成名称规范化、阈值过滤与 NSFW 后处理。理解这一层契约是稳定接入云端或本地视觉模型、保证标签数据质量的第一步。赞分享后端前端图像处理人工智能AI 应用【免费下载链接】photoprismAI-Powered Photos App ✨项目地址https://gitcode.com/gh_mirrors/ph/photoprism点击查看免费下载相关推荐革命性NixOS磁盘管理工具disko告别手动分区实现全自动化部署革命性NixOS磁盘管理工具disko告别手动分区实现全自动化部署 disko是一款专为NixOS设计的声明式磁盘分区和格式化工具它彻底改变了传统手动磁盘ok-ww 鸣潮自动化完整指南后台战斗、刷声骸与一键日常怎么用ok ww 鸣潮自动化完整指南后台战斗、刷声骸与一键日常怎么用 每天上线后先清日常、再打本、再刷声骸这套固定流程很容易占用一两个小时。ok ww 是一款基GUI 自动化计算机视觉RPA人工智能ArkType JSON Schema 互操作指南ark/json-schema 的 Schema 转换与类型安全ArkType JSON Schema 互操作指南 ark/json schema 的 Schema 转换与类型安全 本文是一份关于 ArkType 官方包后端上一篇LTX-2技术路线图未来发展方向与社区期待的新功能下一篇VLC Android打造你的全能移动媒体播放中心创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考