本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用 `fmeval` 程式庫執行自動評估
<a name="clarify-foundation-model-evaluate-auto-lib"></a>

在您自己的程式碼中使用 `fmeval` 程式庫，可讓您最靈活地自訂工作流程。您可以使用 `fmeval` 程式庫評估任何 LLM，也可以更靈活地使用您的自訂輸入資料集。下列步驟說明如何設定您的環境，以及如何使用 `fmeval` 程式庫同時執行啟動和自訂工作流程。

## 開始使用 `fmeval` 程式庫
<a name="clarify-foundation-model-evaluate-auto-lib-get-started"></a>

您可以在 Studio 筆記本中設定基礎模型評估，並針對您的使用案例進行自訂。您的組態取決於您建置的基礎模型要預測的任務類型，以及您想要如何評估它。FMEval 支援開放式生成、文字摘要、問答和分類任務。本節中的步驟說明如何設定開始工作流程。此開始工作流程包括設定您的環境，以及使用 JumpStart 或 Amazon Bedrock 基礎模型搭配內建資料集來執行評估演算法。如果您必須為更具體的使用案例使用自訂輸入資料集和工作流程，請參閱[使用 `fmeval` 程式庫自訂您的工作流程](clarify-foundation-model-evaluate-auto-lib-custom.md)。

## 設定您的環境
<a name="clarify-foundation-model-evaluate-auto-lib-setup"></a>

如果您不想要在 Studio 筆記本中執行模型評估，請跳至下列**開始使用 Studio** 一節中的步驟 11。

**先決條件**
+ 若要在 Studio UI 中執行模型評估，您的 AWS Identity and Access Management (IAM) 角色和任何輸入資料集必須具有正確的許可。如果您沒有 SageMaker AI 網域或 IAM 角色，請遵循 [使用 Amazon SageMaker AI 進行設定的指南](gs.md) 中的步驟。

**為您的 Amazon S3 儲存貯體設定許可**

在建立網域和角色之後，請使用下列步驟來新增評估模型所需的許可。

1. 開啟 Amazon SageMaker AI 主控台，網址為 [https://console.aws.amazon.com/sagemaker/](https://console.aws.amazon.com/sagemaker/)。

1. 在導覽窗格中，將 **S3** 輸入至頁面頂端的搜尋列中。

1. 在**服務**下選擇 **S3**。

1. 從導覽窗格中選擇**儲存貯體**。

1. 在**一般用途儲存貯體**區段的**名稱**下，選擇您要用來在主控台中存放模型輸入和輸出的 S3 儲存貯體名稱。如果您沒有 S3 儲存貯體，請執行下列動作：

   1. 選取**建立儲存貯體**以開啟新的**建立儲存貯體**頁面。

   1. 在**一般組態**區段的 **AWS 區域**下，選取基礎模型所在的 AWS 區域。

   1. 在**儲存貯體名稱**下的輸入方塊中命名您的 S3 儲存貯體。

   1. 接受所有預設選項。

   1. 選取**建立儲存貯體**。

   1. 在**一般用途儲存貯體**區段的**名稱**下，選取您建立的 S3 儲存貯體名稱。

1. 選擇**許可**索引標籤。

1. 捲動至視窗底部的**跨來源資源共用 (CORS)** 區段。選擇**編輯**。

1. 若要將許可新增至儲存貯體以進行基礎評估，請確定下列程式碼出現在輸入方塊中。您也可以複製以下內容並將其貼入輸入方塊中。

   ```
   [
   {
       "AllowedHeaders": [
           "*"
       ],
       "AllowedMethods": [
           "GET",
           "PUT",
           "POST",
           "DELETE"
       ],
       "AllowedOrigins": [
           "*"
       ],
       "ExposeHeaders": [
           "Access-Control-Allow-Origin"
       ]
   }
   ]
   ```

1. 選擇**儲存變更**。

**將許可新增至您的 IAM 政策**

1. 在頁面頂端的搜尋列中，輸入 **IAM**。

1. 在**服務**下，選取 **Identity and Access Management (IAM)**。

1. 從導覽窗格中選擇**政策**。

1. 將 [AmazonSageMakerFullAccess](https://docs.aws.amazon.com/sagemaker/latest/dg/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonSageMakerFullAccess) 輸入至搜尋列。選取出現的政策旁邊的選項按鈕。現在可以選取**動作**按鈕。

1. 選擇**動作**旁邊的向下箭頭。兩個選項隨即出現。

1. 選擇 **Attach** (連接)。

1. 在出現的 IAM 清單，搜尋您建立的角色名稱。選取其名稱旁邊的核取方塊。

1. 選擇**連接政策**。

**開始使用 Studio**

1. 在頁面頂端的搜尋列中，輸入 **SageMaker AI**。

1. 在**服務**下，選取 **Amazon SageMaker AI**。

1. 從導覽窗格中選擇 **Studio**。

1. 在展開**選取網域**下的向下箭頭之後，從**入門**區段中選擇您的網域。

1. 在展開**選取使用者設定檔**下的向下箭頭之後，從**入門**區段中選擇您的使用者設定檔。

1. 選擇**開啟 Studio** 以開啟 Studio 的登陸頁面。

1. 從導覽窗格中選取檔案瀏覽器，然後導覽至根目錄。

1. 選取**建立筆記本**。

1. 在開啟的筆記本環境對話方塊中，選取 **Data Science 3.0** 映像。

1. 選擇**選取**。

1. 在您的開發環境中安裝 `fmeval` 套件，如下列程式碼範例所示：

   ```
   !pip install fmeval
   ```
**注意**  
將 `fmeval` 程式庫安裝到使用 Python 3.10 的環境。如需執行 `fmeval` 所需要求的詳細資訊，請參閱 [`fmeval` 相依性](https://github.com/aws/fmeval/blob/main/pyproject.toml)。

## 設定 `ModelRunner`
<a name="clarify-foundation-model-evaluate-auto-lib-modelrunner"></a>

FMEval 使用稱為 `ModelRunner` 的高階包裝函式來編寫輸入、調用，並從您的模型擷取輸出。`fmeval` 套件可以評估任何 LLM，但設定 `ModelRunner` 的程序取決於您要評估的模型類型。本節說明如何為 JumpStart 或 Amazon Bedrock 模型設定 `ModelRunner`。如果您想要使用自訂輸入資料集和自訂 `ModelRunner`，請參閱[使用 `fmeval` 程式庫自訂您的工作流程](clarify-foundation-model-evaluate-auto-lib-custom.md)。

### 使用 JumpStart 模型
<a name="clarify-foundation-model-evaluate-auto-lib-modelrunner-js"></a>

若要使用 `ModelRunner` 評估 JumpStart 模型，請建立或提供端點、定義模型和內建資料集、設定，然後測試 `ModelRunner`。

**定義 JumpStart 模型並設定 ModelRunner**

1. 執行下列任一動作來提供端點：
   + 將 [EndpointName](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html#API_runtime_InvokeEndpoint_RequestSyntax) 指定為現有的 JumpStart 端點、`model_id` 和 `model_version`。
   + 為您的模型指定 `model_id` 和 `model_version`，並建立 JumpStart 端點。

   下列程式碼範例展示如何為可透過 JumpStart 取得的 [https://aws.amazon.com/blogs/machine-learning/llama-2-foundation-models-from-meta-are-now-available-in-amazon-sagemaker-jumpstart/](https://aws.amazon.com/blogs/machine-learning/llama-2-foundation-models-from-meta-are-now-available-in-amazon-sagemaker-jumpstart/) 建立端點。

   ```
   import sagemaker
   from sagemaker.jumpstart.model import JumpStartModel
   
   #JumpStart model and version
   model_id, model_version = "meta-textgeneration-llama-2-7b-f", "*"
   
   my_model = JumpStartModel(model_id=model_id)
   predictor = my_model.deploy()
   endpoint_name = predictor.endpoint_name
   
   # Accept the EULA, and test the endpoint to make sure it can predict.
   predictor.predict({"inputs": [[{"role":"user", "content": "Hello how are you?"}]]}, custom_attributes='accept_eula=true')
   ```

   先前的程式碼範例是指 EULA，其代表 end-use-license-agreement (EULA)。您可以在所使用模型的模型卡描述中找到 EULA。若要使用某些 JumpStart 模型，您必須指定 `accept_eula=true`，如先前呼叫 `predict` 所示。如需 EULA 的詳細資訊，請參閱[模型來源和授權協議](jumpstart-foundation-models-choose.md)中的**授權和模型來源**一節。

   您可以在[具有預先訓練模型資料表的內建演算法](https://sagemaker.readthedocs.io/en/stable/doc_utils/pretrainedmodels.html#built-in-algorithms-with-pre-trained-model-table)中找到可用的 JumpStart 模型清單。

1. 使用 `JumpStartModelRunner` 設定 `ModelRunner`，如下列組態範例所示：

   ```
   from fmeval.model_runners.sm_jumpstart_model_runner import JumpStartModelRunner
   
   js_model_runner = JumpStartModelRunner(
   endpoint_name=endpoint_name,
   model_id=model_id,
   model_version=model_version
   )
   ```

   在先前的組態範例中，針對 `endpoint_name`、`model_id` 和 `model_version` 使用您用來建立端點的相同值。

1. 測試您的 `ModelRunner`。將範例請求傳送至您的模型，如下列程式碼範例所示：

   ```
   js_model_runner.predict("What is the capital of London")
   ```

### 使用 Amazon Bedrock 模型
<a name="clarify-foundation-model-evaluate-auto-lib-modelrunner-br"></a>

若要評估 Amazon Bedrock 模型，您必須定義模型和內建資料集，並設定 `ModelRunner`。

**定義 Amazon Bedrock 模型並設定 ModelRunner**

1. 若要定義和列印模型詳細資訊，請針對可透過 Amazon Bedrock 取得的 Titan 模型使用下列程式碼範例：

   ```
   import boto3
   import json
   bedrock = boto3.client(service_name='bedrock')
   bedrock_runtime = boto3.client(service_name='bedrock-runtime')
   
   model_id = "amazon.titan-tg1-large"
   accept = "application/json"
   content_type = "application/json"
   
   print(bedrock.get_foundation_model(modelIdentifier=modelId).get('modelDetails'))
   ```

   在先前的程式碼範例中，`accept` 參數會指定您要用來評估 LLM 的資料格式。`contentType` 指定請求中輸入資料的格式。只有 Amazon Bedrock 模型的 `accept` 和 `contentType` 支援 `MIME_TYPE_JSON`。如需這些參數的詳細資訊，請參閱 [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html#API_runtime_InvokeModelWithResponseStream_RequestSyntax)。

1. 若要設定 `ModelRunner`，請使用 `BedrockModelRunner`，如下列組態範例所示：

   ```
   from fmeval.model_runners.bedrock_model_runner import BedrockModelRunner
   
   bedrock_model_runner = BedrockModelRunner(
   model_id=model_id,
   output='results[0].outputText',
   content_template='{"inputText": $prompt, "textGenerationConfig": \
   {"maxTokenCount": 4096, "stopSequences": [], "temperature": 1.0, "topP": 1.0}}',
   )
   ```

   將 `ModelRunner` 組態參數化，如下所示。
   + 針對 `model_id` 使用您用來部署模型的相同值。
   + 使用 `output` 指定所產生 `json` 回應的格式。例如，如果您的 LLM 提供了回應 `[{"results": "this is the output"}]`，則 `output='results[0].outputText'` 會傳回 `this is the output`。
   + 使用 `content_template` 指定 LLM 如何與請求互動。下列組態範本只是為了解釋先前組態範例而詳細說明的，並非必要。
     + 在先前的組態範例中，變數 `inputText` 會指定提示，以擷取使用者提出的請求。
     + 變數 `textGenerationConfig` 指定 LLM 如何產生回應，如下所示：
       + 參數 `maxTokenCount` 用來限制回應的長度，方法是限制 LLM 傳回的字符數量。
       + 參數 `stopSequences` 用來指定字元序列清單，這些序列會告知 LLM 停止產生回應。模型輸出會在輸出中第一次遇到任何列出的字串時停止。例如，您可以使用回車序列，將模型回應限制為單行。
       + 參數 `topP` 透過限制產生下一個字符時要考慮的字符集來控制隨機性。此參數接受介於 `0.0` 和 `1.0` 之間的值。較高的 `topP` 值允許包含更廣泛詞彙的集合，而較低的值會將字符集合限制為更有可能的字詞。
       + 參數 `temperature` 控制所產生文字的隨機性，並接受正值。較高的 `temperature` 值會指示模型產生更多隨機且多樣化的回應。較低的值會產生更能預測的回應。`temperature` 的典型範圍介於 `0.2` 與 `2.0` 之間。

       如需特定 Amazon Bedrock 基礎模型參數的詳細資訊，請參閱[基礎模型的推論參數](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html#model-parameters-titan)。

     content\_template 參數的格式取決於 LLM 支援的輸入和參數。例如，[Anthropic’s Claude 2 模型](https://www.anthropic.com/index/claude-2)可以支援下列 `content_template`：

     ```
     "content_template": "{\"prompt\": $prompt, \"max_tokens_to_sample\": 500}"
     ```

     另一個範例是，[Falcon 7b 模型](https://huggingface.co/tiiuae/falcon-7b)可以支援下列 `content_template`。

     ```
     "content_template": "{\"inputs\": $prompt, \"parameters\":{\"max_new_tokens\": \
     10, \"top_p\": 0.9, \"temperature\": 0.8}}"
     ```

     最後，測試您的 `ModelRunner`。將範例請求傳送至您的模型，如下列程式碼範例所示：

     ```
     bedrock_model_runner.predict("What is the capital of London?")
     ```

## 評估模型
<a name="clarify-foundation-model-evaluate-auto-lib-eval"></a>

設定您的資料和 `ModelRunner` 後，您可以在 LLM 產生的回應上執行評估演算法。若要查看所有可用評估演算法的清單，請執行下列程式碼：

```
from fmeval.eval_algo_mapping import EVAL_ALGORITHMS
print(EVAL_ALGORITHMS.keys())
```

每個演算法都有一個評估和一個 `evaluate_sample` 方法。`evaluate` 方法會計算整個資料集的分數。`evaluate_sample` 方法會評估單一執行個體的分數。

`evaluate_sample` 方法會傳回 `EvalScore` 物件。`EvalScore` 物件包含模型在評估期間執行效果的彙總分數。`evaluate_sample` 方法具有下列選用參數：
+ `model_output` – 單一請求的模型回應。
+ `model_input` – 提示，其中包含對模型的請求。
+ `target_output` – 來自 `model_input` 中所包含提示的預期回應。

以下程式碼範例展示如何使用 `evaluate_sample`。

```
#Evaluate your custom sample
model_output = model_runner.predict("London is the capital of?")[0]
eval_algo.evaluate_sample(target_output="UK<OR>England<OR>United Kingdom", model_output=model_output)
```

`evaluate` 方法具有下列選用參數：
+ `model` – 使用您要評估之模型的 `ModelRunner` 實例。
+ `dataset_config` – 資料集組態。如果未提供 `dataset_config`，則會使用為此任務設定的所有內建資料集評估模型。
+ `prompt_template` – 用來產生提示的範本。如果未提供 `prompt_template`，則會使用預設提示範本評估您的模型。
+ `save` – 如果設定為 `True`，記錄提示回應和分數會儲存到檔案 `EvalAlgorithmInterface.EVAL_RESULTS_PATH`。預設為 `False`。
+ `num_records` – 從輸入資料集隨機抽樣以進行評估的記錄數量。預設為 `300`。

`evaluate` 演算法會傳回可包含下列項目的 `EvalOutput`。物件清單：
+ `eval_name` – 評估演算法的名稱。

  `dataset_name` – 評估演算法使用的資料集名稱。

  `prompt_template` – 用來編寫提示的範本，如果資料集中未提供 `model_output` 參數，則會使用該提示。如需詳細資訊，請參閱**設定 JumpStart`ModelRunner` 一節**中的 `prompt_template`。

  `dataset_scores` – 在整個資料集中計算的彙總分數。

  `category_scores` – `CategoryScore` 物件清單，其中包含資料集中每個類別的分數。

  `output_path` – 評估輸出的本機路徑。此輸出包含具有記錄評估分數的提示回應。

  `error` – 失敗評估任務的字串錯誤訊息。

下列維度可用於模型評估。
+ 準確性
+ 事實知識
+ 提示刻板印像
+ 語意穩健性
+ 毒性

### 準確性
<a name="clarify-foundation-model-evaluate-auto-lib-eval-acc"></a>

您可以針對問答、文字摘要或分類任務執行準確性演算法。為了適應不同的資料輸入類型和問題，每個任務的演算法都不同，如下所示。
+ 對於問答任務，請使用 `QAAccuracyConfig` 檔案執行 `QAAccuracy` 演算法。
+ 對於文字摘要任務，請使用 `SummarizationAccuracyConfig` 執行 `SummarizationAccuracy` 演算法。
+ 對於分類任務，請使用 `ClassificationAccuracyConfig` 執行 `ClassificationAccuracy` 演算法。

`QAAccuracy` 演算法會傳回 `EvalOutput` 物件清單，其中包含每個範例的準確性分數。若要執行問答準確性演算法，請執行個體化 `QAAccuracygeConfig` 並傳入 `<OR>` 或 `None` 做為 `target_output_delimiter`。問答準確性演算法會將模型產生的回應與已知的回應進行比較。如果您傳入 `<OR>` 做為目標分隔符號，則演算法會在答案中產生由 `<OR>` 分隔的任何內容時，將回應評為正確。如果您傳遞 `None` 或空字串做為 `target_output_delimiter`，程式碼會擲回錯誤。

呼叫 `evaluate` 方法並傳入所需的參數，如下列程式碼範例所示：

```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.qa_accuracy import QAAccuracy, QAAccuracyConfig

eval_algo = QAAccuracy(QAAccuracyConfig(target_output_delimiter="<OR>")))
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```

`SummarizationAccuracy` 演算法會傳回 `EvalOutput` 物件清單，其中包含 [https://huggingface.co/spaces/evaluate-metric/rouge](https://huggingface.co/spaces/evaluate-metric/rouge)、[https://huggingface.co/spaces/evaluate-metric/meteor](https://huggingface.co/spaces/evaluate-metric/meteor) 和 [https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore) 的分數。如需這些分數的詳細資訊，請參閱[在模型評估任務中使用提示資料集和可用的評估維度](clarify-foundation-model-evaluate-overview.md)中的文字摘要一節。若要執行文字摘要準確性演算法，請執行個體化 `SummarizationAccuracyConfig` 並傳入以下內容：
+ 將您要在評估中使用的 [https://en.wikipedia.org/wiki/ROUGE_(metric)](https://en.wikipedia.org/wiki/ROUGE_(metric)) 指標類型指定給 `rouge_type`。您可以選擇 `rouge1`、`rouge2` 或 `rougeL`。這些指標會比較產生的摘要與參考摘要。ROUGE-1 會使用重疊的一元語法 (一個項目的序列，例如 “the”、“is”) 來比較產生的摘要與參考摘要。ROUGE-2 會使用二元語法 (兩個序列的群組，例如 “the large”、“is home”) 來比較產生的摘要與參考摘要。ROUGE-L 會比較最長相符的單字序列。如需 ROUGE 的詳細資訊，請參閱 [ROUGE：自動評估摘要的套件](https://aclanthology.org/W04-1013.pdf)。
+ 將 `use_stemmer_for_rouge` 設為 `True` 或 `False`。在比較字詞之前，詞幹提取器會移除字詞的詞綴。例如，詞幹提取器會從 “swimming” 和 “swam” 中移除詞綴，以便它們在詞幹提取之後都是 “swim”。
+ 將 model\_type\_for\_bertscore 設定為您要用來計算 [https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore) 的模型。您可以選擇 [ROBERTA\_MODEL](https://huggingface.co/docs/transformers/model_doc/roberta) 或更進階的 [MICROSOFT\_DEBERTA\_MODEL](https://github.com/microsoft/DeBERTa)。

最後，呼叫 `evaluate` 方法並傳入所需的參數，如下列程式碼範例所示：

```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.summarization_accuracy import SummarizationAccuracy, SummarizationAccuracyConfig

eval_algo = SummarizationAccuracy(SummarizationAccuracyConfig(rouge_type="rouge1",model_type_for_bertscore="MICROSOFT_DEBERTA_MODEL"))
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```

`ClassificationAccuracy` 演算法會傳回 `EvalOutput` 物件清單，其中包含每個範例的分類準確性、精確度、召回率和平衡準確性分數。如需這些分數的詳細資訊，請參閱[在模型評估任務中使用提示資料集和可用的評估維度](clarify-foundation-model-evaluate-overview.md)中的**分類**一節。若要執行分類準確性演算法，請執行個體化 `ClassificationAccuracyConfig` 並將平均策略傳入 `multiclass_average_strategy`。您可以選擇 `micro`、`macro`、`samples`、`weighted` 或 `binary`。預設值為 `micro`。然後，將包含資料欄名稱的清單傳入 valid\_labels，這些資料欄包含分類類別的真實標籤。最後，呼叫 `evaluate` 方法並傳入所需的參數，如下列程式碼範例所示：

```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.classification_accuracy import ClassificationAccuracy, ClassificationAccuracyConfig

eval_algo = ClassificationAccuracy(ClassificationAccuracyConfig(multiclass_average_strategy="samples",valid_labels=["animal_type","plant_type","fungi_type"]))
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```

### 事實知識
<a name="clarify-foundation-model-evaluate-auto-lib-eval-fk"></a>

您可以執行事實知識演算法進行開放式生成。若要執行事實知識演算法，請執行個體化 `FactualKnowledgeConfig` 並選擇性地傳遞分隔符號字串 (根據預設，這是 `<OR>`)。事實知識演算法會將模型產生的回應與已知的回應進行比較。如果演算法在答案中產生以分隔符號分隔的任何內容，則其會將回應評為正確。如果您傳遞 `target_output_delimiter` 做為 `None`，則模型必須產生與答案相同的回應，才能評為正確。最後，呼叫 `evaluate` 方法並傳入所需的參數。

事實知識會傳回 `EvalScore` 物件的清單。這些物件包含有關您的模型多能編碼事實知識的彙總分數，如**基礎模型評估概觀**一節中所述。分數範圍介於 `0` 與 `1` 之間，最低分數對應於較不了解真實世界事實。

下列程式碼範例展示如何使用事實知識演算法評估 LLM：

```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.factual_knowledge import FactualKnowledge, FactualKnowledgeConfig

eval_algo = FactualKnowledge(FactualKnowledgeConfig())
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```

### 提示刻板印像
<a name="clarify-foundation-model-evaluate-auto-lib-eval-ps"></a>

您可以執行提示刻板印象演算法進行開放式生成。若要執行提示刻板印象演算法，您的 `DataConfig` 必須識別輸入資料集中的資料欄，其會在 `sent_less_input_location` 中包含較少刻板印象的句子，以及在 `sent_more_output_location` 中包含較多刻板印象的句子。如需 `DataConfig` 的詳細資訊，請參閱前一節 **2.。Configure (設定)`ModelRunner`**. 接下來，呼叫 `evaluate` 方法並傳入所需的參數。

提示刻板印象會傳回 `EvalOutput` 物件的清單，其中包含每個輸入記錄的分數，以及每種偏差類型的整體分數。分數的計算方式是比較較多刻板印象句子與較少刻板印象句子的機率。整體分數報告模型偏好刻板印象句子的頻率，因為相較於較少刻板印象句子，模型會將較高機率指派給較多刻板印象句子。分數為 `0.5` 表示您的模型是無偏差，或者它以相同的比率偏好較多和較少刻板印象句子。分數大於 `0.5` 表示您的模型可能會產生較多刻板印象的回應。分數小於 `0.5` 表示您的模型可能會產生較少刻板印象的回應。

下列程式碼範例展示如何使用提示刻板印象演算法來評估 LLM：

```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.prompt_stereotyping import PromptStereotyping

eval_algo = PromptStereotyping()
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```

### 語意穩健性
<a name="clarify-foundation-model-evaluate-auto-lib-eval-sr"></a>

您可以針對任何 FMEval 任務執行語意穩健性演算法，但您的模型應該是確定性的。確定性模型是一律為相同輸入產生相同輸出的模型。一個通常可能透過在解碼過程中設定隨機種子來實現確定性。為了適應不同的資料輸入類型和問題，每個任務的演算法都不同，如下所示。
+ 對於開放式生成、問答或任務分類，請使用 `GeneralSemanticRobustnessConfig` 檔案執行 `GeneralSemanticRobustness` 演算法。
+ 對於文字摘要，請使用 `SummarizationAccuracySemanticRobustnessConfig` 檔案執行 `SummarizationAccuracySemanticRobustness` 演算法。

`GeneralSemanticRobustness` 演算法會傳回 `EvalScore` 物件清單，其中包含準確性，其值介於 `0` 與`1` 之間，量化擾動和未擾動模型輸出之間的差異。若要執行一般語意穩健性演算法，請執行個體化 `GeneralSemanticRobustnessConfig` 並傳入 `perturbation_type`。您可以為 `perturbation_type` 選擇下列其中一項：
+ `Butterfinger` - 根據鍵盤距離使用字元交換模擬拼字錯誤的擾動。輸入指定字元被擾動的機率。Butterfinger 是 `perturbation_type` 的預設值。
+ `RandomUpperCase` - 將一小部分字元變更為大寫的擾動。輸入從 `0` 到 `1` 的小數。
+ `WhitespaceAddRemove` - 在非空格字元前面新增空格字元的機率。

您也可以指定以下參數：
+ `num_perturbations` - 要引入所產生文字的每個範例擾動次數。預設值為 `5`。
+ `butter_finger_perturbation_prob` - 擾動字元的機率。只有在 `perturbation_type` 為 `Butterfinger` 時才會使用。預設值為 `0.1`。
+ `random_uppercase_corrupt_proportion` - 要變更為大寫的字元部分。只有在 `perturbation_type` 為 `RandomUpperCase` 時才會使用。預設值為 `0.1`。
+ `whitespace_add_prob` - 假設有一個空格，從範例將其移除的機率。只有在 `perturbation_type` 為 `WhitespaceAddRemove` 時才會使用。預設值為 `0.05`。
+ `whitespace_remove_prob` - 假設有一個非空格，在其前面新增空格的機率。只有在 `perturbation_type` 為 `WhitespaceAddRemove` 時才會使用。預設值為 `0.1`。

最後，呼叫 `evaluate` 方法並傳入所需的參數，如下列程式碼範例所示：

```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.general_semantic_robustness import GeneralSemanticRobustness, GeneralSemanticRobustnessConfig

eval_algo = GeneralSemanticRobustness(GeneralSemanticRobustnessConfig(perturbation_type="RandomUpperCase",num_perturbations=2,random_uppercase_corrupt_proportion=0.3)))
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```

`SummarizationAccuracySemanticRobustness` 演算法會傳回 `EvalScore` 物件清單，其中包含所產生摘要與參考摘要之間 [https://huggingface.co/spaces/evaluate-metric/rouge](https://huggingface.co/spaces/evaluate-metric/rouge)、[https://huggingface.co/spaces/evaluate-metric/meteor](https://huggingface.co/spaces/evaluate-metric/meteor) 和 [https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore) 值之間的差異 (或差值)。如需這些分數的詳細資訊，請參閱[在模型評估任務中使用提示資料集和可用的評估維度](clarify-foundation-model-evaluate-overview.md)中的**文字摘要**一節。若要執行文字摘要語意穩健性演算法，請執行個體化 `SummarizationAccuracySemanticRobustnessConfig` 並傳入 `perturbation_type`。

您可以為 `perturbation_type` 選擇下列其中一項：
+ `Butterfinger` - 根據鍵盤距離使用字元交換模擬拼字錯誤的擾動。輸入指定字元被擾動的機率。`Butterfinger` 是 `perturbation_type` 的預設值。
+ `RandomUpperCase` - 將一小部分字元變更為大寫的擾動。輸入從 `0` 到 `1` 的小數。
+ `WhitespaceAddRemove` - 在非空格字元前面輸入空格字元的機率。

您也可以指定以下參數：
+ `num_perturbations` - 要引入所產生文字的每個範例擾動次數。預設值為 `5`。
+ `butter_finger_perturbation_prob` - 擾動字元的機率。只有在 `perturbation_type` 為 `Butterfinger` 時才會使用。預設值為 `0.1`。
+ `random_uppercase_corrupt_proportion` - 要變更為大寫的字元部分。只有在 `perturbation_type` 為 `RandomUpperCase` 時才會使用。預設值為 `0.1`。
+ `whitespace_add_prob` - 假設有一個空格，從範例將其移除的機率。只有在 `perturbation_type` 為 `WhitespaceAddRemove` 時才會使用。預設值為 `0.05`。
+ `whitespace_remove_prob` - 假設有一個非空格，在其前面新增空格的機率。僅在 `perturbation_type` 為 `WhitespaceAddRemove` 時才使用，預設值為 `0.1`。
+ `rouge_type` - 比較所產生摘要與參考摘要的指標。將您要在評估中使用的 [https://en.wikipedia.org/wiki/ROUGE_(metric)](https://en.wikipedia.org/wiki/ROUGE_(metric)) 指標類型指定給 `rouge_type`。您可以選擇 `rouge1`、`rouge2` 或 `rougeL`。ROUGE-1 會使用重疊的一元語法 (一個項目的序列，例如 “the”、“is”) 來比較產生的摘要與參考摘要。ROUGE-2 會使用二元語法 (兩個序列的群組，例如 “the large”、“is home”) 來比較產生的摘要與參考摘要。ROUGE-L 會比較最長相符的單字序列。如需 ROUGE 的詳細資訊，請參閱 [ROUGE：自動評估摘要的套件](https://aclanthology.org/W04-1013.pdf)。
+ 將 `user_stemmer_for_rouge` 設為 `True` 或 `False`。在比較字詞之前，詞幹提取器會移除字詞的詞綴。例如，詞幹提取器會從 “swimming” 和 “swam” 中移除詞綴，以便它們在詞幹提取之後都是 “swim”。
+ 將 `model_type_for_bertscore` 設定為您要用來計算 [https://huggingface.co/spaces/evaluate-metric/bertscore](https://huggingface.co/spaces/evaluate-metric/bertscore) 的模型。您可以選擇 [ROBERTA\_MODEL](https://huggingface.co/docs/transformers/model_doc/roberta) 或更進階的 [MICROSOFT\_DEBERTA\_MODEL](https://github.com/microsoft/DeBERTa)。

  呼叫 `evaluate` 方法並傳入所需的參數，如下列程式碼範例所示：

  ```
  from fmeval.eval import get_eval_algorithm
  from fmeval.eval_algorithms.summarization_accuracy_semantic_robustness import SummarizationAccuracySemanticRobustness, SummarizationAccuracySemanticRobustnessConfig
  
  eval_algo = SummarizationAccuracySemanticRobustness(SummarizationAccuracySemanticRobustnessConfig(perturbation_type="Butterfinger",num_perturbations=3,butter_finger_perturbation_prob=0.2)))
  eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
  ```

### 毒性
<a name="clarify-foundation-model-evaluate-auto-lib-eval-tox"></a>

您可以執行毒性演算法進行開放式生成、文字摘要或問答。有三種不同的類別，取決於任務。
+ 對於開放式生成，請使用 `ToxicityConfig` 檔案執行毒性演算法。
+ 對於摘要，請使用類別 `Summarization_Toxicity`。
+ 對於問答，請使用類別 `QAToxicity`。

毒性演算法會傳回一或多個 `EvalScore` 物件清單 (取決於毒性偵測器)，其中包含 `0` 與 `1` 之間的分數。若要執行毒性演算法，請執行個體化 `ToxicityConfig` 並傳入毒性模型，以用來在 `model_type` 中評估您的模型。您可以為 `model_type` 選擇下列項目：
+ [適用於 UnitaryAI Detoxify-unbiased 的 `detoxify`](https://github.com/unitaryai/detoxify)，這是針對 [Toxic Comment Classification Challenge](https://www.kaggle.com/c/jigsaw-toxic-comment-classification-challenge) 和 [Jigsaw Unintended Bias in Toxicity Classification](https://www.kaggle.com/c/jigsaw-unintended-bias-in-toxicity-classification) 訓練的多標籤文字分類器。此模型為下列類別提供 `7` 分數：毒性、嚴重毒性、淫穢、威脅、侮辱、性露骨和身分攻擊。

  以下是 detoxity 模型的範例輸出：

  ```
  EvalScore(name='toxicity', value=0.01936926692724228),
  
  EvalScore(name='severe_toxicity', value=3.3755677577573806e-06),
  
  EvalScore(name='obscene', value=0.00022437423467636108),
  
  EvalScore(name='identity_attack', value=0.0006707844440825284),
  
  EvalScore(name='insult', value=0.005559926386922598),
  
  EvalScore(name='threat', value=0.00016682750720065087),
  
  EvalScore(name='sexual_explicit', value=4.828436431125738e-05)
  ```
+ [適用於 Toxigen-roberta 的 `toxigen`](https://github.com/microsoft/TOXIGEN)，這是在 ToxiGen 資料集上微調的 RoBERTa 型二進位文字分類器，該資料集包含與 `13` 少數族群有關的微妙和隱含毒性句子。

最後，呼叫 `evaluate` 方法並傳入所需的參數，如下列程式碼範例所示。

```
from fmeval.eval import get_eval_algorithm
from fmeval.eval_algorithms.toxicity import Toxicity, ToxicityConfig

eval_algo = Toxicity(ToxicityConfig(model_type="detoxify"))
eval_output = eval_algo.evaluate(model=model_runner, dataset_config=config, prompt_template="$feature", save=True)
```