LiteLLM Dashboard 防护栏配置组件实战：Azure 文本审核与 PII 掩码配置组件设计指南

LiteLLM Dashboard 防护栏配置组件实战Azure 文本审核与 PII 掩码配置组件设计指南【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellmLiteLLM 的 Proxy 内置多种护栏Guardrail覆盖 Azure Content Safety 文本审核、基于 Microsoft Presidio 的 PII 检测与掩码等安全能力。本文聚焦 ui/litellm-dashboard/guardrails/_components/README.md) 目录中的 Dashboard 前端配置组件设计文档完整梳理 Azure 文本审核配置组件类别选择、全局阈值、分类别阈值覆盖与 PII 配置组件的组件契约、TSX 集成示例、输出数据结构并结合仓库内真实的后端护栏实现与前端 PII 组件源码帮助你在自己的表单、配置页或自定义管理界面中复用这套“可视化配置→结构化护栏参数”的模式。Azure Text Moderation 配置组件Dashboard 侧的内容安全可视化配置Azure 文本审核配置组件位于仪表盘防护栏配置体系中目标是把 Azure Content Safety 的文本审核参数抽象成直观的表单界面让管理员可以类别选择Category Selection勾选需要监控的内容类别Hate、Sexual、SelfHarm、Violence全局严重级别阈值Global Severity Threshold为所有类别设置统一的默认阈值分类别阈值覆盖Per-Category Thresholds在高级场景下对指定类别单独覆盖全局阈值。这套前端交互产物最终是一条与后端 Azure 文本审核护栏兼容的配置对象可随用户/团队配置一并保存从而在请求进入模型前或返回响应后执行内容安全拦截。组件清单与 Props 契约根据组件目录文档本功能由两个核心组件构成AzureTextModerationConfiguration渲染完整的 Azure 文本审核设置 UI 的主配置组件AzureTextModerationExample演示如何结合 React state 管理集成该配置组件的完整示例。主组件的 TypeScript Props 契约如下interface AzureTextModerationConfigurationProps { categories: string[]; // Available categories selectedCategories: string[]; // Currently selected categories globalSeverityThreshold: number; // Global threshold (0, 2, 4, 6) categorySpecificThresholds: { [key: string]: number }; // Per-category overrides onCategorySelect: (category: string) void; // Category selection handler onGlobalSeverityChange: (threshold: number) void; // Global threshold handler onCategorySeverityChange: (category: string, threshold: number) void; // Per-category handler }注意阈值取值被约束为0、2、4、6四个离散档位Azure “四档严重级别”输出模型下文“严重级别体系”会展开说明。设计上组件保持“受控组件controlled component”风格所有状态由父组件持有并通过回调上抛因此既可以独立嵌入自定义设置弹窗也能与表单状态管理如 React Hook Form无缝对接。集成示例用 React state 驱动配置组件组件目录文档给出了一个开箱即用的集成示例。把AZURE_TEXT_MODERATION_CATEGORIES预定义类别常量映射为categories维护三个 state并在保存时组装成后端可用的配置对象import React, { useState } from react; import { AzureTextModerationConfiguration, AZURE_TEXT_MODERATION_CATEGORIES } from ./guardrails; const MyComponent () { const [selectedCategories, setSelectedCategories] useStatestring[]([Hate, Violence]); const [globalSeverityThreshold, setGlobalSeverityThreshold] useStatenumber(2); const [categorySpecificThresholds, setCategorySpecificThresholds] useState{ [key: string]: number }({}); const handleCategorySelect (category: string) { setSelectedCategories((prev) prev.includes(category) ? prev.filter((c) c ! category) : [...prev, category], ); }; const handleSave () { const config { categories: selectedCategories, severity_threshold: globalSeverityThreshold, severity_threshold_by_category: categorySpecificThresholds, }; // Save to backend... }; return ( AzureTextModerationConfiguration categories{AZURE_TEXT_MODERATION_CATEGORIES.map((c) c.name)} selectedCategories{selectedCategories} globalSeverityThreshold{globalSeverityThreshold} categorySpecificThresholds{categorySpecificThresholds} onCategorySelect{handleCategorySelect} onGlobalSeverityChange{setGlobalSeverityThreshold} onCategorySeverityChange{(category, threshold) setCategorySpecificThresholds((prev) ({ ...prev, [category]: threshold })) } / ); };要点解读handleCategorySelect采用“toggle”语义已选中则移除、未选中则追加保证selectedCategories始终为无重复数组handleSave生成的对象结构categories/severity_threshold/severity_threshold_by_category就是下方“配置输出”中要下发的护栏参数AZURE_TEXT_MODERATION_CATEGORIES由组件目录中的常量文件导出映射后仅向 UI 暴露name字段避免把内部结构耦合进展示层。严重级别体系Severity Levels组件严格采用 Azure Content Safety 的四档严重级别。等级越高的内容越危险只有达到对应阈值才触发拦截Level 0Safe / 安全内容恰当、安全Level 2Low / 低内容在某些语境下可能不合适Level 4Medium / 中内容不合适应予以过滤Level 6High / 高内容有害应直接阻断。这一四档语义与后端实现保持一致Azure 文本审核护栏在发送给 Azure 的请求体中默认设置outputType: FourSeverityLevels即请求 Azure 按四档级别打分见 text_moderation.py。因此前端的阈值下拉只会出现0/2/4/6是与 API 能力严格对齐后的结果。预定义内容类别Content Categories组件预置四个监控类别语义与 Azure Content Safety 的文本审核类别一一对应Hate仇恨基于受保护特征进行攻击或使用歧视性语言的内容Sexual色情描述性行为或其他色情内容SelfHarm自残宣扬、鼓励或描绘自残行为的内容Violence暴力描绘死亡、暴力或身体伤害的内容。后端 AzureContentSafetyTextModerationGuardrail 在未显式传入categories时默认启用的就是这四类同时它还额外支持blocklistNames自定义屏蔽词表与haltOnBlocklistHit命中屏蔽词表即停止两个可选参数说明前端四类选择只是文本审核拦截的一个子集实际能力边界以 Azure API 为准。配置输出Configuration Output组件生成的配置对象与 Azure 文本审核护栏兼容示例输出如下{ categories: [Hate, Violence], severity_threshold: 2, severity_threshold_by_category: { Hate: 4, Violence: 2 } }语义为全局阈值 2低危即开始关注但对 Hate 单独收紧到 4中危才过滤、Violence 保持全局的 2。这份 JSON 可直接作为护栏litellm_params的一部分提交给后端注册与下发入口见 guardrail_endpoints.py。前端字段与后端参数映射契约如何落地把上述输出与后端 Python 实现对照可以看到前端与后端在命名上完全同构前端配置字段后端护栏初始化参数说明categoriescategories需审核的类别缺省为 Hate/Sexual/SelfHarm/Violenceseverity_thresholdseverity_threshold全局阈值后端缺省值为2text_moderation.pyseverity_threshold_by_categoryseverity_threshold_by_category分类别阈值覆盖—可选blocklistNames/haltOnBlocklistHit屏蔽词表与“命中即停”由kwargs透传在 text_moderation.py 的__init__中这些参数被整理进optional_params_request_body作为请求体随每次审核调用发送给 Azure Content Safety API。也就是说前端只负责“把用户选择翻译成结构化的 severity 阈值策略”真正的判定逻辑完全发生在服务端护栏钩子中。PII 配置组件实体检测与 MASK/BLOCK 行为配置组件目录 README 中同样记录了 PII个人身份信息配置沿用与 Azure 审核组件相似的思路用可视化方式完成PII 实体检测与动作MASK / BLOCK的配置属于“已有existing的 PII 配置组件”。与 README 描述平行当前仓库中确实存在一套可运行的 PII 前端组件实现pii_configuration.tsx/guardrails/_components/pii_configuration.tsx)PII 配置主组件同时服务于“新增护栏”与“编辑护栏”两种表单场景组件头注释明确说明“Used in both add and edit guardrail forms”pii_components.tsx/guardrails/_components/pii_components.tsx)底层 UI 部件类别过滤、快捷操作、实体列表类型定义位于 components/guardrails/types.ts与组件目录约定略有出入但契约一致。组件职责拆分PiiConfiguration在内部持有selectedCategoriesstate并通过“实体→类别”的查找映射来按类别过滤展示的实体const [selectedCategories, setSelectedCategories] useStatestring[]([]); const entityToCategoryMap new Mapstring, string(); entityCategories.forEach((category) { category.entities.forEach((entity) { entityToCategoryMap.set(entity, category.category); }); }); const filteredEntities entities.filter((entity) { return selectedCategories.length 0 || selectedCategories.includes(entityToCategoryMap.get(entity) || ); });交互细节包括未选择任何类别时展示全部实体选择类别后仅展示映射命中该类别的实体。UI 上方同时呈现已选数量统计selectedEntities.lengthitems selected与CategoryFilter、QuickActions面板。其 Props 契约来源于 types.ts 中PiiConfigurationProps大致为entities候选实体、actions可选动作、selectedEntities、selectedActions、onEntitySelect/onActionSelect回调以及可选的entityCategories实体按类别分组供过滤用。PiiEntityCategory的字段可由组件用法推出——每个类别拥有category名称与entities实体数组。Quick Actions一键 MASK 或 BLOCKpii_components.tsx/guardrails/_components/pii_components.tsx) 中的QuickActions提供三类快捷入口帮助管理员快速统一策略Select All Mask为全部实体选择 MASK 动作Select All Block为全部实体选择 BLOCK 动作Unselect All一键清空全部选择无选中时按钮置灰。在PiiConfiguration.handleSelectAll中逻辑是遍历全部实体并逐一下发选择与动作事件handleUnselectAll则遍历当前已选项逐个 toggle 以回到空态。getActionIcon为 MASK / BLOCK 分别渲染EyeOff隐藏与Ban禁止图标让实体行上的动作一目了然pii_components.tsx/guardrails/_components/pii_components.tsx#L26-L35)。PII 配置与后端 Presidio 护栏的对应关系服务端对应的实现是 presidio.pyMicrosoft Presidio PII 掩码护栏其中同样定义了PiiAction与PiiEntityType等类型见其from litellm.types.guardrails import ...导入段并引入BlockedPiiEntityError——当策略为 BLOCK 且命中实体时抛出阻断异常。可以推断前端生成的“实体 → MASK/BLOCK”映射最终会落到 Presidio 护栏的 analyze识别与 anonymize掩码/ deny阻断参数上MASK 对应脱敏改写、BLOCK 对应请求中断。实际接入位置可在 add_guardrail_form.tsx/guardrails/_components/add_guardrail_form.tsx#L823) 与 guardrail_info.tsx/guardrails/_components/guardrail_info.tsx) 中看到PiiConfiguration以entityCategories{guardrailSettings.pii_entity_categories}的形式被复用说明实体类别集合由护栏设置guardrailSettings驱动保证“可配置项”来自后端能力而非前端写死。组件的测试与质量保障配置组件并非孤立 UI仓库为该目录配套了大量行为测试可直接作为理解组件边界的“可执行文档”pii_configuration.test.tsx/guardrails/_components/pii_configuration.test.tsx)覆盖 PII 配置主组件的选择/清空/过滤行为pii_components.test.tsx/guardrails/_components/pii_components.test.tsx)覆盖类别过滤、QuickActions、实体列表等子部件的渲染与交互同目录下的 GuardrailsPanel.tsx/guardrails/_components/GuardrailsPanel.tsx)、guardrail_garden.tsx/guardrails/_components/guardrail_garden.tsx)、guardrail_garden_configs.ts/guardrails/_components/guardrail_garden_configs.ts) 等文件则展示了不同护栏类型在新增表单、信息展示与“护栏花园”选择页中如何统一编排佐证“Azure 文本审核”“PII”只是护栏花园中众多可配置类型中的两类。在业务界面中复用这套模式无论是直接使用AzureTextModerationConfiguration还是PiiConfiguration仓库里沉淀出的通用模式都值得借鉴受控组件 纯回调组件不自管持久化所有状态上抛给父级天然适配表单库与“保存”动作前端值与后端契约同构categories / severity_threshold / severity_threshold_by_category等字段与后端护栏litellm_params字段命名一致前端组装即后端可消费降低转换成本能力由后端驱动可选类别、实体分组如guardrailSettings.pii_entity_categories来源于服务端设置前端只渲染与筛选保证新增实体/类别时无需改 UI层级化阈值策略全局默认值 按类别覆盖既保证默认安全水位又允许针对高危类别单独收紧。将 Dashboard 中的选择翻译成结构化护栏参数并交由 Proxy 服务端执行正是 LiteLLM 护栏体系里“管理面可视化配置、数据面强制执行”这一分工的体现。开发者可在此基础上扩展自己的防护栏配置界面先按 README 中的 Props 契约定义展示层再对齐 text_moderation.py 与 presidio.py 中的参数语义生成配置对象即可用同一套 UI 覆盖从内容安全审核到 PII 脱敏的完整护栏配置闭环。【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100 LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考