
🐢 用于 LLM 智能体的开源评估与测试库
<p align="center">
<img alt="giskardlogo" src="https://assets.kitploit.com/production/public/readmes/50936/c1f328b3f3cefd9e527b0ff1f2991be7d3336ce13cd265993c62b57ce676cab5/a720b322f89a71f208538a57a11e96baef88a9c0bafe7779659f1b4bafcfc27e-display-v1.webp">
<img alt="giskardlogo" src="https://assets.kitploit.com/production/public/readmes/50936/2fd9c4a7c2204d367db301019e2fc0e3de34eacd445004fd705b27cbb7aff5fc/ab0feb5722a650948a83c6cdc420dc43f15ae5e7a8000d26b22fd7effb8f1ca8-display-v1.webp">
</p>
<h1 align="center" weight='300' >面向智能体系统的评估、红队测试与测试生成</h1>
<h3 align="center" weight='300' >模块化、轻量、动态且异步优先</h3>
<div align="center">
[](https://github.com/Giskard-AI/giskard-oss/releases)
[](https://github.com/Giskard-AI/giskard/blob/main/LICENSE)
[](https://pepy.tech/project/giskard)
[](https://github.com/Giskard-AI/giskard-oss/actions/workflows/ci.yml/badge.svg?branch=main)
[](https://gisk.ar/discord)
<a rel="me" href="https://fosstodon.org/@Giskard"></a>
</div>
<h3 align="center">
<a href="https://docs.giskard.ai/oss"><b>文档</b></a> •
<a href="https://www.giskard.ai/?utm_source=github&utm_medium=github&utm_campaign=github_readme&utm_id=readmeblog"><b>网站</b></a> •
<a href="https://gisk.ar/discord"><b>社区</b></a>
</h3>
<br />
> [!IMPORTANT]
> **Giskard v3** 是一次全新重写,专为 AI 智能体的动态、多轮测试而设计。此版本移除了沉重的依赖以提升效率,同时引入了更强大的 AI 漏洞扫描器和增强的 RAG 评估——两者现已在 `giskard-scan` 中原生提供,不再依赖 v2。仅针对**表格/机器学习模型**的旧版扫描仍仅限 v2。
> **Giskard v2 仍可使用,但已不再积极维护。**
> 关注进展 → [阅读 v3 公告](https://github.com/orgs/Giskard-AI/discussions/2250) · [路线图](https://github.com/Giskard-AI/giskard-oss/issues/2252)
## 安装
```sh
pip install giskard # checks (+ agents, llm, core)
pip install "giskard[scan]" # + vulnerability / quality scan
pip install "giskard[openai]" # provider SDK for LLM judges / generators
```
需要 Python 3.12+。
| Extra | 新增内容 |
| --- | --- |
| *(无)* | `giskard-checks` 及其依赖 |
| `scan` | `giskard-scan` |
| `openai` / `anthropic` / … | 提供商 SDK(参见 `pyproject.toml` 中的可选依赖) |
**遥测:** 通过 `giskard-core` 进行可选的聚合分析。不会发送任何提示词或输出。
可通过 `export DO_NOT_TRACK=1` 或 `export GISKARD_TELEMETRY_DISABLED=1` 退出(或在工作目录的 `.env` 文件中设置相同的键)。在导入前设置可跳过创建 `~/.giskard/id`;稍后设置仍会停止后续发送。
详情:[`giskard-core` README](https://github.com/giskard-ai/giskard-oss/blob/main/libs/giskard-core/README.md#telemetry)。
---
Giskard 是一个用于**测试和评估智能体系统**的开源 Python 库。v3 架构是一组模块化的专注包——每个包只携带其所需的依赖——从零构建以封装任何对象:一个 LLM、一个黑盒智能体,或一个多步骤流水线。
| 状态 | 包 | 描述 |
| -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ✅ 稳定 | `giskard-checks` | 测试与评估——场景 API、内置检查、LLM-as-judge |
| ✅ 稳定 | `giskard-scan` | 智能体漏洞扫描器 + RAG/质量评估——红队测试、提示词注入、越狱与有害内容(`vulnerability_scan`,[v2 Scan](https://legacy-docs.giskard.ai/en/stable/open_source/scan/index.html) 的继任者),以及知识库质量评估(`quality_scan`,[v2 RAGET](https://legacy-docs.giskard.ai/en/stable/open_source/testset_generation/index.html) 的继任者) |
这些包构建于三个基础库之上——`giskard-core`(共享工具与遥测)、`giskard-llm`(提供商无关的 LLM 路由)和 `giskard-agents`(智能体与工作流编排)——它们会被自动引入,很少直接使用。
## Giskard Checks — 创建并应用用于测试智能体的评估
```sh
pip install giskard-checks
```
**[Giskard Checks](https://docs.giskard.ai/oss/checks)** 是一个轻量级库,用于创建评估(evals),以测试基于 LLM 的系统——从简单的断言到 LLM-as-judge 评估。与传统单元测试不同,评估专为**非确定性输出**而设计,即相同的输入可能产生不同的有效响应。
使用 Giskard Checks 可以:
- **捕获回归** — 验证系统在更改后是否仍能正确运行
- **验证 RAG 质量** — 检查答案是否基于检索到的上下文
- **执行安全规则** — 确保输出符合你的内容策略
- **评估多轮智能体** — 测试完整对话,而不仅仅是单次交互
内置评估包括字符串匹配、比较、正则表达式、语义相似度以及 LLM-as-judge 检查(`Groundedness`、`Conformity`、`LLMJudge`)。
### 概念
- **Target** — 被测系统:任何同步/异步可调用对象 `(inputs) -> outputs`(可选带 `trace`)
- **Scenario** — 一次评估:交互 + 检查
- **Check** — 对 trace 的断言或 LLM 评判
- **Suite** — 一起运行的多个场景
`giskard.agents.Generator` 是用于工作流/评判器的 LLM 客户端——与
`giskard.checks` 中用于合成用户消息的输入生成器(`LLMGenerator`)不同。
### 快速开始
在没有运行事件循环的脚本中:
```python
from giskard.checks import Scenario, Groundedness
def get_answer(inputs: str) -> str:
return "Paris" # replace with your model / agent
scenario = (
Scenario("test_france_capital")
.interact(inputs="What is the capital of France?", outputs=get_answer)
.check(
Groundedness(
name="answer is grounded",
context="France is in Western Europe. Its capital is Paris.",
)
)
)
result = scenario.run_sync()
result.print_report()
```
在 notebook 单元格中或异步函数内部,改为 await 该场景:
```python
result = await scenario.run()
result.print_report()
```
`Groundedness` 是一个 LLM 评判器——安装一个提供商扩展(例如 `pip install "giskard[openai]"`)并设置对应的 API 密钥。默认模型:`openai/gpt-4o-mini`。
有关 `Suites`、`LLMJudge`、多轮场景等更多内容,请参阅[完整文档](https://docs.giskard.ai/oss/checks)。
---
## Giskard Scan — AI 智能体漏洞扫描器
```sh
pip install "giskard[scan]" # or: pip install giskard-scan
```
**Giskard Scan** 是面向智能体系统的红队测试与漏洞扫描层。它能够根据对您智能体的自然语言描述自动生成对抗性测试套件,覆盖提示注入、有害内容、刻板印象、虚假信息等更多类别。
使用 Giskard Scan 可以:
- **对您的智能体进行红队测试** — 自动生成覆盖 OWASP LLM Top-10 威胁类别的对抗性输入
- **运行提示注入探测** — 内置可直接使用的注入载荷数据集
- **通过自定义生成器进行扩展** — 将您自己的 `ScenarioGenerator` 实例传给 `generate_suite`,或在 `vulnerability_suite_generator_registry` 上注册它们
### 快速开始
```python
import asyncio
from giskard.scan import vulnerability_scan
async def my_agent(inputs: str) -> str:
# Replace with your agent / model call
return f"Echo: {inputs}"
async def main() -> None:
await vulnerability_scan(
target=my_agent,
description="A customer support chatbot for an e-commerce platform.",
languages=["en"],
)
asyncio.run(main())
```
扫描生成器同样需要 LLM 提供方扩展和 API 密钥(与上文 Checks 评判器相同)。
## 在寻找 Giskard v2?
Giskard v2 包含 **Scan**(自动漏洞检测)和 **RAGET**(RAG 评估测试集生成)。
对于 **LLM 智能体**,这两者在 v3 中均已被 `giskard-scan` 取代:使用 [`vulnerability_scan`](#giskard-scan--vulnerability-scanner-for-ai-agents) 替代 v2 的 LLM 扫描,并使用 `quality_scan`(配合 `KnowledgeBase`)替代 RAGET。
v3 同样适用于 ML 模型——将模型包装为目标,并使用 `giskard-checks` 或 `giskard-scan` 对其进行评估。以下示例涵盖的是 **仅限 v2 的自动表格扫描**——即通过内省 `giskard.Model` + `giskard.Dataset` 来自动检测性能、偏差和鲁棒性问题的检测器套件——以及 `giskard.testing` ML 测试套件和 Giskard Hub。这些内容未计划在 v3 中提供。
```sh
pip install "giskard[llm]>2,<3"
```
### [Scan](https://legacy-docs.giskard.ai/en/stable/open_source/scan/index.html) — 自动检测性能、偏见与安全问题
封装你的模型并运行扫描:
```python
import giskard
import pandas as pd
# Replace my_llm_chain with your actual LLM chain or model inference logic
def model_predict(df: pd.DataFrame):
"""The function takes a DataFrame and must return a list of outputs (one per row)."""
return [my_llm_chain.run({"query": question}) for question in df["question"]]
giskard_model = giskard.Model(
model=model_predict,
model_type="text_generation",
name="My LLM Application",
description="A question answering assistant",
feature_names=["question"],
)
scan_results = giskard.scan(giskard_model)
display(scan_results)
```
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/50936/0e863e60ab4173f4812139f38ba772f996644774946dc27aca07ffb1271f5626/9df9e5e47d8be5ce2e756bdd7315613fecc468a1e6096030cbc25d147a50cdf3-display-v1.webp" alt="扫描示例" width="800">
</p>
### [RAGET](https://legacy-docs.giskard.ai/en/stable/open_source/testset_generation/index.html) — 为 RAG 应用生成评估数据集
从你的知识库中自动生成问题、参考答案和上下文:
```python
import pandas as pd
from giskard.rag import generate_testset, KnowledgeBase
# Load your knowledge base documents
df = pd.read_csv("path/to/your/knowledge_base.csv")
knowledge_base = KnowledgeBase.from_pandas(df, columns=["column_1", "column_2"])
testset = generate_testset(
knowledge_base,
num_questions=60,
language="en",
agent_description="A customer support chatbot for company X",
)
```
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/50936/65cc932276b9d3a86425700b3717748e952a622722b9e129ff43efb0fb91c4d1/1f8abfc8a571f084d70ddfe3c484ad8ecf71d362e52cebfcb8581af12be8c0e9-display-v1.webp" alt="RAGET 示例" width="800">
</p>
[完整的 v2 文档](https://legacy-docs.giskard.ai)
<h1 id="community">👋 社区</h1>
我们欢迎来自 AI 社区的贡献!请阅读这份[指南](https://github.com/giskard-ai/giskard-oss/blob/main/CONTRIBUTING.md)以开始参与,并加入我们在 [Discord](https://gisk.ar/discord) 上蓬勃发展的社区。
关注进展并分享反馈:
[v3 公告](https://github.com/orgs/Giskard-AI/discussions/2250) · [路线图](https://github.com/Giskard-AI/giskard-oss/issues/2252)
🌟 [为我们点亮一颗星](https://github.com/Giskard-AI/giskard),这有助于让项目被更多人发现,也让我们保持动力去构建出色的开源工具!🌟
❤️ 如果你觉得我们的工作有用,请考虑在 GitHub 上[赞助我们](https://github.com/sponsors/Giskard-AI)。通过每月赞助,你可以获得赞助者徽章、在此 readme 中展示你的公司,并让你的 bug 报告获得优先处理。如果你希望我们参与咨询项目、举办工作坊或在你的公司做演讲,我们也提供一次性赞助。