garak 接入 IBM watsonx.aiWatsonXGenerator 的配置、IAM 认证与两种部署调用方式详解【免费下载链接】garakthe LLM vulnerability scanner项目地址: https://gitcode.com/GitHub_Trending/ga/garak导读本文基于 garak 开源项目the LLM vulnerability scanner中的 garak/generators/watsonx.py 及其测试代码系统讲解如何让 garak 调用 IBM watsonx.ai 平台上的基础模型project 阶段与已部署的微调模型deployment 阶段。读完本文你将掌握WatsonXGenerator的全部配置参数与四个环境变量的作用、IAM Bearer Token 的换取流程、两种 REST 请求的报文结构以及 garak 底层generate()调度链如何与 watsonx 接口对接并了解对应的测试验证方法。一、生成器定位garak 眼中的 watsonx 模型garak 通过Generator基类抽象所有待测的文本生成系统garak/generators/base.py。WatsonXGenerator正是针对 IBM watsonx.ai 平台的实现它继承自Generatorgenerator_family_name watsonx模块末尾通过DEFAULT_CLASS WatsonXGenerator声明默认入口类garak/generators/watsonx.py。该类支持两种使用场景与 watsonx.ai 的模型生命周期对应Project 阶段模型平台上的基础模型如ibm/granite-3-8b-instruct通过 Project ID 直接调用文本生成 APIDeployment 阶段模型经过微调tuned并部署的模型通过 Deployment ID 调用部署端点。从源码 docstring 看使用前必须初始化三个环境变量环境变量用途WATSONX_TOKENIBM Cloud API Key用于换取 IAM Bearer TokenWATSONX_URL对应服务实例所在区域的 REST API 基地址WATSONX_PROJECTID或WATSONX_DEPLOYID二选一分别对应 project 模型与已部署模型二、构造与全部配置参数WatsonXGenerator的默认参数在类属性DEFAULT_PARAMS中定义它是在基类Generator.DEFAULT_PARAMS基础上合并扩展的garak/generators/watsonx.pyDEFAULT_PARAMS Generator.DEFAULT_PARAMS | { uri: None, # watsonx REST API 基地址可留空由环境变量 WATSONX_URL 提供 version: 2023-05-29, # watsonx API 版本号 project_id: , # Project ID用于调用 project 阶段模型 deployment_id: , # Deployment ID用于调用已部署的微调模型 prompt_variable: input,# 部署调用中 prompt 变量的名称 bearer_token: , # IAM Bearer Token首次调用时自动获取 max_tokens: 900, # 最大生成 token 数 }各参数说明uriREST API 基地址。留空时_validate_env_var()会回退读取WATSONX_URL环境变量若两者都未提供则抛出ValueError。versionwatsonx API 版本号默认2023-05-29会拼接到每个请求的 query string 中。project_id/deployment_id二者至少填一个可直接传参也可留空交给环境变量。如果两个都为空_validate_env_var()会抛出ValueError。prompt_variable仅 deployment 调用路径使用作为prompt_variables字典的键名。bearer_token缓存的 IAM 令牌为空时在首次_call_model()时通过 API Key 自动换取。max_tokensproject 调用路径中parameters.max_new_tokens的取值默认 900明显大于基类默认的 150说明该实现默认面向较长的生成输出。构造时的 API Key 注入构造函数在调用super().__init__()之后有一个特殊动作garak/generators/watsonx.pydef __init__(self, name, config_root_config): super().__init__(name, config_rootconfig_root) if self.api_key is not None: os.environ[self.ENV_VAR] self.api_key也就是说api_key的取值优先级高于环境变量无论api_key来自命令行--model_api_key还是配置文件只要非空就会覆盖写回WATSONX_TOKEN环境变量。而api_key本身的读取依赖configurable.py中_validate_env_var()的通用逻辑garak/configurable.py只要类定义了ENV_VAR且未显式提供api_key就从WATSONX_TOKEN环境变量读取。三、IAM 认证如何换取 Bearer Token_set_bearer_token()实现了标准的 IBM Cloud IAM API Key 认证流程garak/generators/watsonx.pydef _set_bearer_token(self, iam_urlhttps://iam.cloud.ibm.com/identity/token): header { Content-Type: application/x-www-form-urlencoded, Accept: application/json, } body ( grant_typeurn:ibm:params:oauth:grant-type:apikeyapikey self.api_key ) response requests.post(urliam_url, headersheader, databody) self.bearer_token Bearer response.json()[access_token]要点使用application/x-www-form-urlencoded表单提交grant type 为 IBM 专用的urn:ibm:params:oauth:grant-type:apikey默认请求https://iam.cloud.ibm.com/identity/token但iam_url可覆盖测试即利用该参数将请求指向 mock 地址换取到的access_token会以Bearer 前缀缓存到self.bearer_token后续所有 watsonx 请求的Authorization头都复用该值。测试 tests/generators/test_watsonx.py 用requests_mock模拟identity/token端点断言granite_llm.bearer_token等于Bearer access_token验证了认证逻辑的正确性。mock 响应结构见 tests/_assets/generators/watsonx.json包含access_token、expiration、expires_in、token_type等字段。四、两种调用路径Project ID 与 Deployment ID_call_model()根据是否配置了deployment_id选择调用路径garak/generators/watsonx.py只要deployment_id非空就走部署端点否则走 project 端点。两种请求均通过requests.post发送 JSON并携带三个固定的请求头Accept: application/json、Content-Type: application/json、Authorization: bearer_token。4.1 Project 路径_generate_with_project(payload)请求端点POST {uri}/ml/v1/text/generation?version{version}请求体garak/generators/watsonx.py{ input: prompt, parameters: { decoding_method: greedy, max_new_tokens: 900, min_new_tokens: 0, repetition_penalty: 1 }, model_id: generator name, project_id: project id }几个值得注意的实现细节model_id直接取自生成器的name也就是说实例化WatsonXGenerator时传入的名称如ibm/granite-3-8b-instruct就是 watsonx 平台上的模型标识。测试 tests/generators/test_watsonx.py 正是通过断言granite_llm.name response[model_id]来验证这一点生成参数是硬编码的贪婪解码decoding_methodgreedy、min_new_tokens0、repetition_penalty1最大化确定性这对漏洞扫描场景非常重要——同一 prompt 的多次探测结果应当可复现max_new_tokens与max_tokens参数挂钩调整生成器配置中的max_tokens即可控制输出长度上限。4.2 Deployment 路径_generate_with_deployment(payload)请求端点garak/generators/watsonx.pyPOST {uri}/ml/v1/deployments/{deployment_id}/text/generation?version{version}请求体{ parameters: { prompt_variables: { input: prompt } } }部署端点使用prompt_variables机制传递输入变量名即配置参数prompt_variable默认input。注意与 project 路径不同deployment 路径不传model_id模型身份由部署端点自身决定。测试 tests/generators/test_watsonx.py 通过拼接/ml/v1/deployments/{deployment_id}/text/generation?version2023-05-29的 mock 地址来验证该请求路径。五、响应解析与空 prompt 防护5.1 从响应中提取生成文本无论哪条路径最终统一按 watsonx 的响应格式解析garak/generators/watsonx.pyreturn [Message(.join(output[results][0][generated_text]))]即取results[0].generated_text并包装为 garak 的Message对象。watsonx 响应结构参见 mock 数据 tests/_assets/generators/watsonx.json顶层含model_id、model_version、created_atresults数组中每项含generated_text、generated_token_count、input_token_count、stop_reason等字段。5.2 空 prompt 的 null byte 防护garak 的某些探测器可能产生空字符串 prompt而 watsonx API 不接受空输入。_call_model()对此做了防御garak/generators/watsonx.pyif not prompt or not prompt.last_message().text: prompt Conversation([Turn(user, Message(\x00))]) print(WARNING: Empty prompt was found. Null byte character appended to prevent API failure.)当输入为空时会替换为包含 null byte\x00的Conversation并打印警告避免 API 调用直接失败——这是保证漏洞扫描流程不因异常输入中断的关键健壮性设计。5.3 与 garak 生成调度链的对接WatsonXGenerator只实现了_call_model()未覆盖generate()因此完整复用基类Generator.generate()的调度逻辑garak/generators/base.py先执行_pre_generate_hook()再按generations_this_call决定单次调用、多次串行调用或parallel_requests多进程并行调用最后执行_post_generate_hook()与可选的skip_seq_start/skip_seq_end序列裁剪。由于supports_multiple_generations默认False当 garak 探测器请求多个 generations 时会以串行或并行方式多次调用_call_model()。六、环境变量校验规则_validate_env_var()是配置正确性的最后一道闸门garak/generators/watsonx.py按以下顺序校验URLuri未配置时读取WATSONX_URL仍为空则抛出ValueError提示需要填入服务实例所在区域的 URLProject IDproject_id未配置时读取WATSONX_PROJECTIDDeployment IDdeployment_id未配置时读取WATSONX_DEPLOYID二选一约束若project_id与deployment_id均为空抛出ValueError提示必须提供 Project ID 或 Deployment ID最后调用父类_validate_env_var()完成api_key的兜底读取从WATSONX_TOKEN。该方法的优先级设计是显式参数 环境变量与构造函数中api_key覆盖WATSONX_TOKEN的行为保持一致。测试夹具 tests/generators/test_watsonx.py 展示了完整的环境变量模拟方式同时设置四个变量的假值并在测试结束后通过addfinalizer恢复原始环境。七、快速接入与验证7.1 命令行接入示例配置好环境变量后即可用 garak 的--model_type参数指定 watsonx 生成器garak CLI 会将生成器名解析为watsonx家族export WATSONX_TOKENyour-ibm-cloud-api-key export WATSONX_URLhttps://us-south.ml.cloud.ibm.com export WATSONX_PROJECTIDyour-project-id # 或 export WATSONX_DEPLOYIDyour-deployment-id garak --model_type watsonx --model_name ibm/granite-3-8b-instruct --probes promptinject其中--model_name在 project 路径下会作为model_id直接发送给 watsonx因此必须是平台上真实存在的模型标识。若使用已部署的微调模型则仅需WATSONX_DEPLOYID而不传模型名。7.2 运行测试验证仓库为 watsonx 生成器提供了三组离线测试依赖requests_mock拦截 HTTP 请求不会产生真实调用pytest tests/generators/test_watsonx.py -vtest_bearer_token验证 IAM token 换取与Bearer前缀拼接test_project验证 project 路径请求体中的model_id与生成器名称一致test_deployment验证 deployment 端点 URL 的拼接格式。相关 mock 数据与夹具分别位于 tests/_assets/generators/watsonx.json 和 tests/generators/conftest.py。八、实现要点小结关注点结论源码位置认证用WATSONX_TOKENAPI Key经 IAM 换取 Bearer Token缓存在bearer_tokengarak/generators/watsonx.py模型选择Project 路径用name作为model_idDeployment 路径由部署端点决定garak/generators/watsonx.py解码策略硬编码贪婪解码greedy、min_new_tokens0、repetition_penalty1保证扫描结果确定性garak/generators/watsonx.py输出长度由max_tokens默认 900控制映射到max_new_tokensgarak/generators/watsonx.py健壮性空 prompt 自动追加 null byte防止 API 失败garak/generators/watsonx.py调度集成仅实现_call_model()复用基类generate()的串行/并行多 generation 逻辑garak/generators/base.py从源码结构看WatsonXGenerator是 garak 生成器体系中典型的薄封装实现它不重新发明调度框架而是专注解决 watsonx 特有的认证、URL 构造、请求报文与响应解析其余能力全部继承自Generator基类。这也意味着在 garak 中使用它时探测器的多 generation 请求、parallel_requests并行加速、输出裁剪skip_seq_start/skip_seq_end等通用能力均可开箱即用无需额外配置。【免费下载链接】garakthe LLM vulnerability scanner项目地址: https://gitcode.com/GitHub_Trending/ga/garak创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考