ashishawasthi/hrz-ai-quality-model-risk
GitHub: ashishawasthi/hrz-ai-quality-model-risk
一个六边形架构的 AI 质量与模型风险治理平台，通过结合自动化评估与红队对抗测试来充当模型发布门禁。
Stars: 0 | Forks: 0
# A4：AI 质量与模型风险平台
[](.github/workflows/ci.yaml)
[](.github/workflows/eval-gate.yaml)
[](LICENSE)
[](pyproject.toml)
## 1. A4 产出的内容
A4 接收一个 **target**（一个模型 + 一个 prompt 版本 + 一个 golden 数据集）并返回四个 artifact，每个都附带其背后的证据：
| # | Artifact | 领域类型 | 服务 |
|---|----------|-------------|---------|
| 1 | **EvalReport**：每个 metric 的得分 / 阈值 / 是否通过 | `EvalReport` | `EvaluationService.evaluate()` |
| 2 | **RedTeamReport**：五大攻击家族下每个 probe 的通过/失败情况 | `RedTeamReport` | `RedTeamService.run()` |
| 3 | **GateDecision**：PASS/FAIL 的发布裁决 + MRM 证据 | `GateDecision` | `PromotionGateService.gate()` |
| 4 | **ModelCard** + **PromptVersion**：带版本的 MRM 证据 | `ModelCard`, `PromptVersion` | `ModelCardService`, `PromptVersioningService` |
当且仅当 EvalReport 越过每一个 metric 阈值，并且 RedTeamReport 阻断每一个 probe 时，一个 target 才算作**通过**。目录标识：**A4**，所属组 **`hrz`**（共享平台服务），优先级 **P0**，买方 **Model Risk / MLOps**。A4 **不**处理客户 PII（它根据数据集评估模型），因此规则 R1 / A1 为 **N/A**。
每一个 artifact、metric 和决策都是 [`src/ai_quality/domain/models.py`](src/ai_quality/domain/models.py) 中纯粹基于标准库的 dataclass，这是六边形架构的核心，对 Google Cloud、ADK 或任何框架的依赖为**零**。
## 2. 架构：六边形
领域核心负责所有的编排，并且只与 **port**（Python `Protocol`）进行交互。三个可互换的 adapter 家族实现了这些 port。将整个托管 stack 切换到本地部署只需进行**一行 profile 更改**（`AI_QUALITY_PROFILE`），无需修改领域代码，这就是通用原则 **P-02**（无厂商锁定）的证明。
```
flowchart TB
subgraph edges["Driving adapters (inbound)"]
API["FastAPI gate service
api/"] CLI["Typer CLI
cli/"] UI["React / Next.js UI
ui/"] A2A["A2A / MCP server
agent/"] end subgraph core["Domain core: pure Python, no GCP imports"] direction TB MODELS["domain/models.py
(targets, reports, gate, model cards)"] SVCS["Services: Evaluation · RedTeam ·
PromotionGate · PromptVersioning ·
ModelCard · GateReviewPolicy"] THRESH["domain/thresholds.py"] MODELS --- SVCS --- THRESH end subgraph ports["Ports (11 Protocols): the hexagon boundary"] P1["Evaluation · RedTeam"] P2["PromptRegistry · ModelCardStore · MetricsStore"] P3["KnowledgeBaseClient (A2) · LLM judge"] P4["AuditSink · Tracer (A5)"] P5["AgentRegistry (A3) · ToolCatalog"] end subgraph gcp["adapters/gcp/*: primary (managed services)"] G["Gen AI evaluation service · Gemini judge ·
BigQuery · Cloud Storage CMEK ·
Cloud Logging WORM · Cloud Trace"] end subgraph plat["adapters/platform/*: hrz-* HTTP clients"] PL["A2 Knowledge Base · A5 Audit · A3 Registry"] end subgraph onp["adapters/onprem/*: placeholder stubs"] ON["NotImplementedError stubs that satisfy
the same Protocols (P-02 / P-12 exit story)"] end edges --> core core --> ports ports --> gcp ports --> plat ports --> onp ``` - **驱动（入站）adapter**：API、CLI、UI 以及 A2A/MCP server。 - **领域核心**：服务通过组合 port 调用来构建四个 artifact。它从不导入云 SDK。 - **Port**：位于 [`src/ai_quality/ports/`](src/ai_quality/ports/) 下的 11 个 `@runtime_checkable` `typing.Protocol`。 - **被驱动（出站）adapter**：`gcp`（真实 SDK 调用，延迟导入），`platform`（连接 `hrz-*` 服务的 HTTP 客户端），`onprem`（占位 stub）。 有关完整的 port 表、gate pipeline 时序图和运行时拓扑结构，请参见 [`ARCHITECTURE.md`](ARCHITECTURE.md)。 ## 3. 锁定的 GCP 技术栈（当前 GA 名称，2026 年中期） | 关注点 | 服务（当前名称） | 标识符 | |---------|------------------------|------------| | Agent 框架 | ADK (Python) | `google-adk==2.3.0` | | 推理 / 评判模型 | Gemini 3.5 Flash | `gemini-3.5-flash` (thinking=high) | | 分流模型 | Gemini 3.1 Flash-Lite | `gemini-3.1-flash-lite` | | Eval 后端 | Gen AI evaluation service | `vertexai.Client(...).evals` | | Red-team 测试工具 | Gemini 驱动的对抗性 probe | `google-genai` | | Eval 指标 / 漂移 | BigQuery | `google-cloud-bigquery` | | Golden 数据集 / 模型卡片 | Cloud Storage (CMEK) | `google-cloud-storage` | | 审计 (WORM) | Cloud Logging 锁定存储桶 | 保留 2557 天（约 7 年） | | 链路追踪 | 通过 OpenTelemetry 的 Cloud Trace | 内容捕获 **关闭** | | 发布 CI | Cloud Build 触发器 | P-08 gate | | 互操作性 | A2A v1.0 + MCP 2025-11-25 | AgentCard `/.well-known/agent-card.json` | | 数据主权 | VPC-SC、区域 CMEK、组织策略 | `asia-southeast1` | **构建中遵循的注意事项**（SPEC §3）：用于满足属地要求的区域端点 + 每个服务独立的 CMEK；span 中的消息内容捕获**关闭**；锁定的日志存储桶是**不可逆的**（保留期是一个 Terraform 变量）；构建**绝不**使用浮动的 ADK 默认模型或 `gemini-2.0-flash`。 ## 4. 快速开始 ### 4.1 `onprem` profile：无需 GCP，随处运行 本地部署 profile 将每个 port 绑定到一个占位 adapter，并在测试套件和 CLI 的本地模式下通过**内存 fake** 来演练系统。**不需要 Google Cloud SDK。** 核心依赖非常轻量，而 GCP SDK 位于 `[gcp]` extra 中。 ``` git clone https://github.com/ashishawasthi/hrz-ai-quality-model-risk.git cd hrz-ai-quality-model-risk python3.12 -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" # core + dev tooling, NO google-cloud-* packages export AI_QUALITY_PROFILE=onprem make lint test # ruff + mypy + pytest -m 'not integration' make eval # the A4 self-eval gate ``` 契约测试确认本地占位 adapter 满足与 GCP adapter 相同的 11 个 Protocol（接口对等），而单元测试则使用内存 fake 来驱动领域服务。这就是让**退出 / 可移植性**方案（P-12）成为现实而不仅仅是愿景的原因；请参见 [`docs/onprem-migration.md`](docs/onprem-migration.md)。 ### 4.2 `gcp` profile：`asia-southeast1` 中真实的托管 stack ``` pip install -e ".[gcp,dev]" # adds google-adk, google-genai, bigquery, storage, ... export GOOGLE_CLOUD_PROJECT=your-sg-project export AI_QUALITY_PROFILE=gcp # the default export AI_QUALITY_KMS_KEY="projects/.../locations/asia-southeast1/keyRings/.../cryptoKeys/..." gcloud auth application-default login make tf-plan # review, then terraform apply (see docs/runbook.md) make run-api # FastAPI gate on :8084, profile=gcp ``` 一切都由 [`config/settings.yaml`](config/settings.yaml) 决定，它会在加载时解析 `${ENV_VAR}` token。切换 profile 永远不会触及代码。 ## 5. 运行三个交互界面 | 界面 | 命令 | 说明 | |---------|---------|-------| | **API** (FastAPI) | `make run-api` | REST gate + 位于 `/.well-known/agent-card.json` 的 A2A AgentCard；OpenAPI 位于 `/docs`。端口 8084。 | | **CLI** (Typer) | `ai-quality gate gemini-3.5-flash v3 compliance-qa-golden` | 入口点 `ai-quality`。子命令 `evaluate`、`redteam`、`gate`、`version-prompt`、`serve`、`eval`。 | | **UI** (React / Next.js) | `make run-ui` | 与 API 通信；渲染 EvalReport、RedTeamReport 和 GateDecision。 | CLI 在 `onprem` profile 下端到端运行，无需任何云访问权限。注意：在 `onprem` 下，eval / red-team 后端是占位 stub，因此 `gate` 会报告清晰的 profile 错误（退出码 2）并指明迁移目标；而**自评 gate**（`make eval`）完全在离线状态下运行，因为它使用确定性的 fake 来驱动真实的 gate 逻辑。 ## 6. 发布 gate (A4 / P-08) 目录中没有任何构建在未通过 A4 的情况下会被发布。该 gate 结合了两个独立的检查，并在裁决背后写入 MRM 证据： ``` sequenceDiagram autonumber actor Caller as Promotion pipeline participant Gate as PromotionGateService participant Eval as EvaluationService participant KB as KnowledgeBaseClient (A2) participant Red as RedTeamService participant Card as ModelCardStore participant Pol as GateReviewPolicy participant Aud as AuditSink (WORM) Caller->>Gate: gate(target, dataset, cases, actor) Gate->>Eval: evaluate(target, dataset) Eval->>KB: retrieve(reference context) KB-->>Eval: reference passages Eval-->>Gate: EvalReport (per-metric pass) Gate->>Red: run(target, cases) Red-->>Gate: RedTeamReport (per-probe pass) Gate->>Card: put(ModelCard, MRM evidence) Gate->>Pol: requires_review(borderline pass?) Pol-->>Gate: requires_human_review (P-06) Gate->>Aud: record(AuditEvent, verdict) Gate-->>Caller: GateDecision (passed, evidence, caveats) ``` ``` make eval # runs eval/run_eval.py; non-zero exit fails the gate ``` CI 在 [`.github/workflows/eval-gate.yaml`](.github/workflows/eval-gate.yaml) 中强制执行此操作。 有关它如何映射到模型风险原则（P-08），请参见 [`COMPLIANCE.md`](COMPLIANCE.md)。 ## 7. 安全与数据主权态势 | 控制 | 执行方式 | |---------|--------------------| | **区域锁定** (`asia-southeast1`) | 每个服务和 SDK 调用都指向新加坡；对于非新加坡区域，Terraform 会**快速失败**。无全局端点。 | | **VPC Service Controls** | 所有托管服务都位于服务边界内，因此 eval metric、golden 数据集、模型卡片和审计无法外泄。 | | **CMEK**（区域级） | 客户管理的 Cloud KMS 密钥加密 BigQuery、Cloud Storage 和日志存储桶（CMEK 不会级联，P-09）。 | | **WORM 审计** (**P-07**) | `CloudLoggingAuditAdapter` 将每一个 gate / eval / red-team `AuditEvent` 写入一个**锁定的** Cloud Logging 存储桶（保留 2557 天，不可逆）。 | | **无内容的链路追踪** | 通过 OpenTelemetry 使用 Cloud Trace，消息内容捕获**关闭**：span 仅包含结构和 token 使用情况，绝不包含 prompt/response 文本。 | | **Maker-checker** (**P-06**) | `GateReviewPolicy` 会标记边缘的 PASS 结果，以供模型风险官员签字确认。 | | **无虚假 PASS** | 空的 golden 数据集是硬错误，绝不会是免费的 PASS；失败的后端会产生失败的报告，绝不会导致崩溃。 | | **退出 / 可移植性** (**P-12**) | `adapters/onprem/*` 占位符 + [`docs/onprem-migration.md`](docs/onprem-migration.md) 记录了零领域更改下向 Google Distributed Cloud 的迁移。 | 本仓库中**每个**通用原则（P-01..P-12）和依赖规则（R1..R6）与具体控制的完整映射位于 [`COMPLIANCE.md`](COMPLIANCE.md) 中。 ## 8. 平台依赖 A4 依赖于三个同类的 `hrz-*` 平台服务。独立部署时，`gcp` adapter 使用 BigQuery / Cloud Logging / 本地注册表；在完整平台内部署时，`platform` adapter 通过 HTTP 进行委托（契约见 [`SPEC.md`](SPEC.md) §6）。 | 依赖 | 仓库 | 它支持的 A4 port | `platform` adapter | |-----|------|-------------------|--------------------| | **A2** 企业知识库 | `hrz-enterprise-knowledge-base` | `KnowledgeBaseClientPort`（基于事实的 eval） | `RemoteKnowledgeBaseAdapter` | | **A5** 可观测性/审计 | `hrz-agent-observability` | `AuditSinkPort` (R2) | `RemoteAuditAdapter` | | **A3** 注册表 | `hrz-agent-registry` | `AgentRegistryPort` (R4) | `RemoteRegistryAdapter` | A4 自身满足规则 **R5**：它是其他所有 agent 在发布前调用的 gate。 ## 9. 仓库布局 ``` flowchart LR root["hrz-ai-quality-model-risk/"] src["src/ai_quality/"] domain["domain/
models.py, services, thresholds, hitl: pure, no cloud"] ports["ports/
11 Protocols (the hexagon boundary)"] adapters["adapters/"] gcp["gcp/
primary managed-service adapters (lazy GCP SDK imports)"] platform["platform/
thin HTTP clients to hrz-* services"] onprem["onprem/
NotImplementedError placeholder stubs (P-02 / P-12)"] agent["agent/
ADK agent + A2A/MCP server wiring"] api["api/
FastAPI gate service"] cli["cli/
Typer CLI (entry point: ai-quality)"] pipelines["pipelines/
golden dataset + red-team case loaders"] srcconfig["config.py
Settings + Container (DI for the hexagon)"] config["config/settings.yaml
port -> adapter bindings, region, models, retention"] eval["eval/
run_eval.py + golden sets + rubrics (the self-eval gate)"] terraform["infra/terraform/
asia-southeast1 infra (BigQuery, GCS, WORM bucket)"] ui["ui/
React / Next.js app"] tests["tests/
contract + unit tests (run under the onprem profile)"] docs["docs/
onprem-migration.md, runbook.md"] topdocs["SPEC.md · ARCHITECTURE.md · COMPLIANCE.md"] root --> src src --> domain src --> ports src --> adapters adapters --> gcp adapters --> platform adapters --> onprem src --> agent src --> api src --> cli src --> pipelines src --> srcconfig root --> config root --> eval root --> terraform root --> ui root --> tests root --> docs root --> topdocs ``` ## 10. 文档导览 - [`SPEC.md`](SPEC.md)：权威的构建规范（锁定的决策、锁定的 stack、adapter 约定、gate pipeline、HTTP 契约）。 - [`ARCHITECTURE.md`](ARCHITECTURE.md)：11-port 表、gate 时序图、运行时拓扑结构和平台依赖。 - [`COMPLIANCE.md`](COMPLIANCE.md)：映射到本仓库中具体控制的每一个通用原则和依赖规则。 - [`docs/onprem-migration.md`](docs/onprem-migration.md)：退出/可移植性核对清单。 - [`docs/runbook.md`](docs/runbook.md)：部署、区域快速失败、密钥轮换、保留期。 - [`CONTRIBUTING.md`](CONTRIBUTING.md)：如何设置、lint、测试和贡献。 ## 许可证 Apache-2.0 © 2026 Ashish Awasthi。请参见 [`LICENSE`](LICENSE)。
api/"] CLI["Typer CLI
cli/"] UI["React / Next.js UI
ui/"] A2A["A2A / MCP server
agent/"] end subgraph core["Domain core: pure Python, no GCP imports"] direction TB MODELS["domain/models.py
(targets, reports, gate, model cards)"] SVCS["Services: Evaluation · RedTeam ·
PromotionGate · PromptVersioning ·
ModelCard · GateReviewPolicy"] THRESH["domain/thresholds.py"] MODELS --- SVCS --- THRESH end subgraph ports["Ports (11 Protocols): the hexagon boundary"] P1["Evaluation · RedTeam"] P2["PromptRegistry · ModelCardStore · MetricsStore"] P3["KnowledgeBaseClient (A2) · LLM judge"] P4["AuditSink · Tracer (A5)"] P5["AgentRegistry (A3) · ToolCatalog"] end subgraph gcp["adapters/gcp/*: primary (managed services)"] G["Gen AI evaluation service · Gemini judge ·
BigQuery · Cloud Storage CMEK ·
Cloud Logging WORM · Cloud Trace"] end subgraph plat["adapters/platform/*: hrz-* HTTP clients"] PL["A2 Knowledge Base · A5 Audit · A3 Registry"] end subgraph onp["adapters/onprem/*: placeholder stubs"] ON["NotImplementedError stubs that satisfy
the same Protocols (P-02 / P-12 exit story)"] end edges --> core core --> ports ports --> gcp ports --> plat ports --> onp ``` - **驱动（入站）adapter**：API、CLI、UI 以及 A2A/MCP server。 - **领域核心**：服务通过组合 port 调用来构建四个 artifact。它从不导入云 SDK。 - **Port**：位于 [`src/ai_quality/ports/`](src/ai_quality/ports/) 下的 11 个 `@runtime_checkable` `typing.Protocol`。 - **被驱动（出站）adapter**：`gcp`（真实 SDK 调用，延迟导入），`platform`（连接 `hrz-*` 服务的 HTTP 客户端），`onprem`（占位 stub）。 有关完整的 port 表、gate pipeline 时序图和运行时拓扑结构，请参见 [`ARCHITECTURE.md`](ARCHITECTURE.md)。 ## 3. 锁定的 GCP 技术栈（当前 GA 名称，2026 年中期） | 关注点 | 服务（当前名称） | 标识符 | |---------|------------------------|------------| | Agent 框架 | ADK (Python) | `google-adk==2.3.0` | | 推理 / 评判模型 | Gemini 3.5 Flash | `gemini-3.5-flash` (thinking=high) | | 分流模型 | Gemini 3.1 Flash-Lite | `gemini-3.1-flash-lite` | | Eval 后端 | Gen AI evaluation service | `vertexai.Client(...).evals` | | Red-team 测试工具 | Gemini 驱动的对抗性 probe | `google-genai` | | Eval 指标 / 漂移 | BigQuery | `google-cloud-bigquery` | | Golden 数据集 / 模型卡片 | Cloud Storage (CMEK) | `google-cloud-storage` | | 审计 (WORM) | Cloud Logging 锁定存储桶 | 保留 2557 天（约 7 年） | | 链路追踪 | 通过 OpenTelemetry 的 Cloud Trace | 内容捕获 **关闭** | | 发布 CI | Cloud Build 触发器 | P-08 gate | | 互操作性 | A2A v1.0 + MCP 2025-11-25 | AgentCard `/.well-known/agent-card.json` | | 数据主权 | VPC-SC、区域 CMEK、组织策略 | `asia-southeast1` | **构建中遵循的注意事项**（SPEC §3）：用于满足属地要求的区域端点 + 每个服务独立的 CMEK；span 中的消息内容捕获**关闭**；锁定的日志存储桶是**不可逆的**（保留期是一个 Terraform 变量）；构建**绝不**使用浮动的 ADK 默认模型或 `gemini-2.0-flash`。 ## 4. 快速开始 ### 4.1 `onprem` profile：无需 GCP，随处运行 本地部署 profile 将每个 port 绑定到一个占位 adapter，并在测试套件和 CLI 的本地模式下通过**内存 fake** 来演练系统。**不需要 Google Cloud SDK。** 核心依赖非常轻量，而 GCP SDK 位于 `[gcp]` extra 中。 ``` git clone https://github.com/ashishawasthi/hrz-ai-quality-model-risk.git cd hrz-ai-quality-model-risk python3.12 -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" # core + dev tooling, NO google-cloud-* packages export AI_QUALITY_PROFILE=onprem make lint test # ruff + mypy + pytest -m 'not integration' make eval # the A4 self-eval gate ``` 契约测试确认本地占位 adapter 满足与 GCP adapter 相同的 11 个 Protocol（接口对等），而单元测试则使用内存 fake 来驱动领域服务。这就是让**退出 / 可移植性**方案（P-12）成为现实而不仅仅是愿景的原因；请参见 [`docs/onprem-migration.md`](docs/onprem-migration.md)。 ### 4.2 `gcp` profile：`asia-southeast1` 中真实的托管 stack ``` pip install -e ".[gcp,dev]" # adds google-adk, google-genai, bigquery, storage, ... export GOOGLE_CLOUD_PROJECT=your-sg-project export AI_QUALITY_PROFILE=gcp # the default export AI_QUALITY_KMS_KEY="projects/.../locations/asia-southeast1/keyRings/.../cryptoKeys/..." gcloud auth application-default login make tf-plan # review, then terraform apply (see docs/runbook.md) make run-api # FastAPI gate on :8084, profile=gcp ``` 一切都由 [`config/settings.yaml`](config/settings.yaml) 决定，它会在加载时解析 `${ENV_VAR}` token。切换 profile 永远不会触及代码。 ## 5. 运行三个交互界面 | 界面 | 命令 | 说明 | |---------|---------|-------| | **API** (FastAPI) | `make run-api` | REST gate + 位于 `/.well-known/agent-card.json` 的 A2A AgentCard；OpenAPI 位于 `/docs`。端口 8084。 | | **CLI** (Typer) | `ai-quality gate gemini-3.5-flash v3 compliance-qa-golden` | 入口点 `ai-quality`。子命令 `evaluate`、`redteam`、`gate`、`version-prompt`、`serve`、`eval`。 | | **UI** (React / Next.js) | `make run-ui` | 与 API 通信；渲染 EvalReport、RedTeamReport 和 GateDecision。 | CLI 在 `onprem` profile 下端到端运行，无需任何云访问权限。注意：在 `onprem` 下，eval / red-team 后端是占位 stub，因此 `gate` 会报告清晰的 profile 错误（退出码 2）并指明迁移目标；而**自评 gate**（`make eval`）完全在离线状态下运行，因为它使用确定性的 fake 来驱动真实的 gate 逻辑。 ## 6. 发布 gate (A4 / P-08) 目录中没有任何构建在未通过 A4 的情况下会被发布。该 gate 结合了两个独立的检查，并在裁决背后写入 MRM 证据： ``` sequenceDiagram autonumber actor Caller as Promotion pipeline participant Gate as PromotionGateService participant Eval as EvaluationService participant KB as KnowledgeBaseClient (A2) participant Red as RedTeamService participant Card as ModelCardStore participant Pol as GateReviewPolicy participant Aud as AuditSink (WORM) Caller->>Gate: gate(target, dataset, cases, actor) Gate->>Eval: evaluate(target, dataset) Eval->>KB: retrieve(reference context) KB-->>Eval: reference passages Eval-->>Gate: EvalReport (per-metric pass) Gate->>Red: run(target, cases) Red-->>Gate: RedTeamReport (per-probe pass) Gate->>Card: put(ModelCard, MRM evidence) Gate->>Pol: requires_review(borderline pass?) Pol-->>Gate: requires_human_review (P-06) Gate->>Aud: record(AuditEvent, verdict) Gate-->>Caller: GateDecision (passed, evidence, caveats) ``` ``` make eval # runs eval/run_eval.py; non-zero exit fails the gate ``` CI 在 [`.github/workflows/eval-gate.yaml`](.github/workflows/eval-gate.yaml) 中强制执行此操作。 有关它如何映射到模型风险原则（P-08），请参见 [`COMPLIANCE.md`](COMPLIANCE.md)。 ## 7. 安全与数据主权态势 | 控制 | 执行方式 | |---------|--------------------| | **区域锁定** (`asia-southeast1`) | 每个服务和 SDK 调用都指向新加坡；对于非新加坡区域，Terraform 会**快速失败**。无全局端点。 | | **VPC Service Controls** | 所有托管服务都位于服务边界内，因此 eval metric、golden 数据集、模型卡片和审计无法外泄。 | | **CMEK**（区域级） | 客户管理的 Cloud KMS 密钥加密 BigQuery、Cloud Storage 和日志存储桶（CMEK 不会级联，P-09）。 | | **WORM 审计** (**P-07**) | `CloudLoggingAuditAdapter` 将每一个 gate / eval / red-team `AuditEvent` 写入一个**锁定的** Cloud Logging 存储桶（保留 2557 天，不可逆）。 | | **无内容的链路追踪** | 通过 OpenTelemetry 使用 Cloud Trace，消息内容捕获**关闭**：span 仅包含结构和 token 使用情况，绝不包含 prompt/response 文本。 | | **Maker-checker** (**P-06**) | `GateReviewPolicy` 会标记边缘的 PASS 结果，以供模型风险官员签字确认。 | | **无虚假 PASS** | 空的 golden 数据集是硬错误，绝不会是免费的 PASS；失败的后端会产生失败的报告，绝不会导致崩溃。 | | **退出 / 可移植性** (**P-12**) | `adapters/onprem/*` 占位符 + [`docs/onprem-migration.md`](docs/onprem-migration.md) 记录了零领域更改下向 Google Distributed Cloud 的迁移。 | 本仓库中**每个**通用原则（P-01..P-12）和依赖规则（R1..R6）与具体控制的完整映射位于 [`COMPLIANCE.md`](COMPLIANCE.md) 中。 ## 8. 平台依赖 A4 依赖于三个同类的 `hrz-*` 平台服务。独立部署时，`gcp` adapter 使用 BigQuery / Cloud Logging / 本地注册表；在完整平台内部署时，`platform` adapter 通过 HTTP 进行委托（契约见 [`SPEC.md`](SPEC.md) §6）。 | 依赖 | 仓库 | 它支持的 A4 port | `platform` adapter | |-----|------|-------------------|--------------------| | **A2** 企业知识库 | `hrz-enterprise-knowledge-base` | `KnowledgeBaseClientPort`（基于事实的 eval） | `RemoteKnowledgeBaseAdapter` | | **A5** 可观测性/审计 | `hrz-agent-observability` | `AuditSinkPort` (R2) | `RemoteAuditAdapter` | | **A3** 注册表 | `hrz-agent-registry` | `AgentRegistryPort` (R4) | `RemoteRegistryAdapter` | A4 自身满足规则 **R5**：它是其他所有 agent 在发布前调用的 gate。 ## 9. 仓库布局 ``` flowchart LR root["hrz-ai-quality-model-risk/"] src["src/ai_quality/"] domain["domain/
models.py, services, thresholds, hitl: pure, no cloud"] ports["ports/
11 Protocols (the hexagon boundary)"] adapters["adapters/"] gcp["gcp/
primary managed-service adapters (lazy GCP SDK imports)"] platform["platform/
thin HTTP clients to hrz-* services"] onprem["onprem/
NotImplementedError placeholder stubs (P-02 / P-12)"] agent["agent/
ADK agent + A2A/MCP server wiring"] api["api/
FastAPI gate service"] cli["cli/
Typer CLI (entry point: ai-quality)"] pipelines["pipelines/
golden dataset + red-team case loaders"] srcconfig["config.py
Settings + Container (DI for the hexagon)"] config["config/settings.yaml
port -> adapter bindings, region, models, retention"] eval["eval/
run_eval.py + golden sets + rubrics (the self-eval gate)"] terraform["infra/terraform/
asia-southeast1 infra (BigQuery, GCS, WORM bucket)"] ui["ui/
React / Next.js app"] tests["tests/
contract + unit tests (run under the onprem profile)"] docs["docs/
onprem-migration.md, runbook.md"] topdocs["SPEC.md · ARCHITECTURE.md · COMPLIANCE.md"] root --> src src --> domain src --> ports src --> adapters adapters --> gcp adapters --> platform adapters --> onprem src --> agent src --> api src --> cli src --> pipelines src --> srcconfig root --> config root --> eval root --> terraform root --> ui root --> tests root --> docs root --> topdocs ``` ## 10. 文档导览 - [`SPEC.md`](SPEC.md)：权威的构建规范（锁定的决策、锁定的 stack、adapter 约定、gate pipeline、HTTP 契约）。 - [`ARCHITECTURE.md`](ARCHITECTURE.md)：11-port 表、gate 时序图、运行时拓扑结构和平台依赖。 - [`COMPLIANCE.md`](COMPLIANCE.md)：映射到本仓库中具体控制的每一个通用原则和依赖规则。 - [`docs/onprem-migration.md`](docs/onprem-migration.md)：退出/可移植性核对清单。 - [`docs/runbook.md`](docs/runbook.md)：部署、区域快速失败、密钥轮换、保留期。 - [`CONTRIBUTING.md`](CONTRIBUTING.md)：如何设置、lint、测试和贡献。 ## 许可证 Apache-2.0 © 2026 Ashish Awasthi。请参见 [`LICENSE`](LICENSE)。
标签：AI安全, Chat Copilot, DLL 劫持, MLOps, 人工智能, 大语言模型, 模型评估, 用户代理, 用户模式Hook绕过, 逆向工具