LocalAI 本地内容审核：基于约束 JSON 生成实现 OpenAI 兼容的 /v1/moderations 端点

LocalAI 本地内容审核基于约束 JSON 生成实现 OpenAI 兼容的 /v1/moderations 端点【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAILocalAI 通过POST /v1/moderations提供 OpenAI 兼容的文本内容审核能力核心思路是用一个本地文本生成模型加受限 JSON 语法constrained JSON grammar完成安全分类无需任何独立的审核服务或云 API。读完本文你将掌握该端点的请求/响应格式、13 个分类标签体系、基于语法规则约束模型输出的实现机制以及路由注册、权限控制和错误处理等可直接落地的细节。端点与请求格式LocalAI 暴露了 OpenAI 兼容的审核端点POST /v1/moderations由一个本地文本生成模型完成分类不依赖独立的 moderation 服务或云端 API。可以直接用 curl 调用curl http://localhost:8080/v1/moderations \ -H Content-Type: application/json \ -d { model: your-instruct-model, input: Text to classify }其中input既可以是单个字符串也可以是字符串数组批量审核。这一点在请求 schema 中通过自定义 JSON 反序列化实现ModerationInput 的UnmarshalJSON会先尝试按字符串解析失败后再尝试按字符串数组解析两者都不匹配则返回input must be a text string or array of text strings错误。对应的请求结构体为type ModerationRequest struct { BasicModelRequest Input ModerationInput json:input }除/v1/moderations外路由注册文件 中还同时注册了不带版本前缀的/moderations路径两者挂载同一个处理函数。响应格式每条输入对应一个结果ModerationResponse与ModerationResult的定义见 core/schema/moderation.go字段类型说明idstring响应 ID以modr-前缀加 UUID 生成modelstring回显请求中的模型名results[].flaggedbool任一分类命中即为true所有类别布尔值的 ORresults[].categoriesmap[string]bool每个分类的布尔判定结果results[].category_scoresmap[string]float64每个分类 0~1 的置信度分数results[].category_applied_input_typesmap[string][]string每个分类适用的输入类型当前恒为[text]测试用例 moderations_test.go 验证了批量输入会得到逐条结果、flagged与categories的联动关系以及category_applied_input_types固定为[text]。分类标签体系与 OpenAI moderation API 对齐源码中定义了 13 个分类标签moderationCategories一级分类细分标签harassment骚扰harassment/threateninghate仇恨hate/threateningillicit非法illicit/violentself-harm自残self-harm/intent、self-harm/instructionssexual性内容sexual/minorsviolence暴力violence/graphic这 13 个标签同时出现在分类提示词、JSON 语法的必填字段列表以及结果解析的校验逻辑中三者强一致保证模型输出必须覆盖全部分类。约束生成如何保证模型只输出合法 JSON这是该功能的核心机制。端点实现 moderationEndpoint 在每次请求时做三件事构造分类提示词moderationPrompt 将待分类文本 JSON 编码后拼入提示词要求模型只返回语法要求的 JSON 对象对每个分类给出 0~1 的置信度Classify the supplied text for safety moderation. Return only the JSON object required by the grammar. For each category, set the boolean to true only when the text matches that category. Give each category a confidence score from 0 to 1. The categories are harassment, harassment/threatening, hate, hate/threatening, illicit, illicit/violent, self-harm, self-harm/intent, self-harm/instructions, sexual, sexual/minors, violence, and violence/graphic. Text to classify: JSON编码后的文本若模型启用了 tokenizer 模板UseTokenizerTemplate提示词会包装为一条 user 消息交由模板渲染否则通过 模板求值器 套用补全提示模板并可继承模型配置中的SystemPrompt。构建 JSON 语法约束moderationGrammar 动态生成一个 JSON Schema——categories为全部 13 个布尔字段、category_scores为全部 13 个数字字段均声明required且additionalProperties: false再经 JSONFunctionStructure.Grammar() 转换为推理后端可执行的约束语法。同时端点将Maxtokens强制设为 512限制输出长度。严格解析与校验parseModerationResult 解析模型原始输出逐分类检查布尔值是否存在、分数是否缺失或落在 0~1 区间之外NaN/Inf 也视为非法任一失败即整体报错绝不返回部分结果。这个提示词 语法约束 解析校验的组合意味着LocalAI 约束的是输出形状而分类质量与置信度分数完全由所选模型决定——这也是文档强调选用指令微调模型的原因。路由注册与中间件链路由与中间件配置见 core/http/routes/openai.gonodeHeaderMiddleware/usageMiddleware/traceMiddleware节点标识、token 用量统计与请求追踪re.BuildFilteredFirstAvailableDefaultModel(config.BuildUsecaseFilterFn(config.FLAG_COMPLETION))未显式指定模型时自动挑选第一个支持补全completion能力用例的可用模型——这从机制上解释了所选模型必须支持文本补全这一要求re.BuildConstantDefaultModelNameMiddleware(gpt-4o)兼容客户端写死gpt-4o等 OpenAI 模型名的场景middleware.AdmissionControl(...)准入控制并发/准入限制。每次推理完成后端点会通过middleware.StampUsage将累计的 prompt/completion token 用量写回请求上下文因此该端点的 token 消耗可被统一计量。鉴权与权限开关在多用户鉴权模式下/v1/moderations与/moderations均绑定FeatureModeration功能位core/http/auth/features.go功能元数据标签为 Moderation 且默认启用默认值为true见 features.go 及 features_moderation_test.go。管理员可对单个用户关闭该权限对应测试见 middleware_test.go。输入校验与错误处理端点对外部输入和模型输出都有明确的失败路径测试文件 moderations_test.go 覆盖了这些行为场景行为依据input为空数组/缺失400input must contain at least one text stringmoderations.go某条文本为空白字符串400input strings must not be emptymoderations.go模型输出无法解析为约定 JSON500invalid moderation result: ...不返回部分结果moderations_test.goinput传入 OpenAI 风格多模态对象如image_url反序列化阶段报错input must be a text string or array of text stringsmoderations_test.go模型选择与当前限制模型要求所选模型必须支持文本补全从源码结构看分类效果依赖模型遵循安全分类提示词的能力因此官方建议使用指令微调instruction-tuned模型以获得稳定的分类质量与置信度。仅支持文本当前实现只处理纯文本OpenAI 风格含图片的多模态输入对象会在校验阶段直接报错。schema 注释 表明一旦具备可用的视觉审核路径即可在不改变响应契约的前提下扩展多模态审核。参考文件文档docs/content/features/moderation.md端点实现core/http/endpoints/openai/moderations.go请求/响应 schemacore/schema/moderation.go路由与中间件core/http/routes/openai.go端点测试core/http/endpoints/openai/moderations_test.go权限位定义core/http/auth/features.go语法转换pkg/functions/function_structure.go【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考