llm-evals

一個用於評估大型語言模型（LLM）在多種任務上表現的框架，支援非同步批次推論、Azure OpenAI 及本地部署端點。

支援的任務

任務類型	TaskType	LLM 角色	說明
多選題問答	`QA`	受測模型	LLM 直接作答，評估選擇正確選項的能力
工具呼叫	`TOOLCALLING`	受測模型	LLM 進行 Function Calling，支援自訂資料集與 BFCL 格式
查核價值判斷	`CHECKWORTHINESS`	受測模型	LLM 判斷一個聲明是否具有查核價值
聲明證據立場	`CLAIMEVIDENCESTANCE`	受測模型 / NLI	LLM（或外部 NLI 服務）判斷證據對聲明的支持、反對或無關立場
摘要生成評估	`SUMMARIZATION`	G-Eval 評審	LLM 以評審角色打分，指標：Relevance / Coherence / Consistency / Fluency
事實抽取評估	`FACTEXTRACTION`	G-Eval 評審	LLM 以評審角色打分，指標：Quality / Completeness
問答生成評估	`QAGENERATE`	G-Eval 評審	LLM 以評審角色打分，指標：Relevance / Accuracy / Fluency
FAQ 回應評估	`FAQRESPONSE`	G-Eval 評審	LLM 以評審角色打分，指標：Completeness / Relevance / Coherence / Fluency / Consistency/ Actionability / Evidence Use / Conciseness
生成聲明評估	`GENERATECLAIMS`	G-Eval 評審	LLM 以評審角色打分，指標：Factual Accuracy / Coverage / Redundancy
生成真相評估	`GENERATETRUTHS`	G-Eval 評審	LLM 以評審角色評估從文件生成真相陳述的品質
RAG 檢索評估	`RAG`	不需要 LLM	僅需 Embedding + Reranking 模型，評估向量搜尋與 BM25 混合檢索的準確率

安裝

需求： Python >= 3.9

# 安裝套件
pip install -e .

設定模型 Config

複製範例設定檔並填入您的 API 資訊：

cp config/example_models.yaml config/models.yaml

config/models.yaml 範例：

params:
    default:
        temperature: 0.2
        max_tokens: 1000
        top_p: 1

LLM_engines:
    gpt-4o:
        model: "gpt-4o"
        azure_api_base: "https://your-resource.openai.azure.com/"
        azure_api_key: "your_azure_api_key"
        azure_api_version: "2024-02-01"
    Qwen3-14B:
        model: "Qwen3-14B"
        local_api_key: "Empty"
        local_base_url: "http://localhost:8000/v1"
        translate_to_cht: true   # 可選：將輸出轉換為繁體中文

embedding_models:
    bge-m3:
        model: "bge-m3"
        local_api_key: "Empty"
        local_base_url: "http://localhost:8001/v1"

reranking_models:
    bge-reranker-large:
        model: "bge-reranker-large"
        local_api_key: "Empty"
        local_base_url: "http://localhost:8002/v1"

LLM_engines：模型名稱以 gpt 開頭（且不含 oss）時，自動使用 AzureOpenAI；否則使用本地 OpenAI 相容端點。
translate_to_cht：設為 true 時，模型輸出會透過 OpenCC 轉換為繁體中文。

EvalPipeline：多任務批次評估

EvalPipeline 可以在一支腳本中串接多個任務，統一管理 batch_size、輸出目錄，並自動產生執行摘要報告。

快速開始

from src.api.async_llm_client import AsyncLLMChat
from src.pipeline import EvalPipeline, PipelineStep
from src.tasks.base_task import TaskConfig, TaskType

llm = AsyncLLMChat(model="Qwen3-14B", config_path="./config/models.yaml")

pipeline = EvalPipeline(output_folder="output")

pipeline.add(PipelineStep(
    task_type=TaskType.QA,
    dataset_paths="./datasets/qa/example_qa.json",   # 單一路徑或 list 皆可
    config=TaskConfig(task_type=TaskType.QA, llm=llm, llm_params={...}),
    name="QA-Qwen3-14B",
))
pipeline.add(PipelineStep(
    task_type=TaskType.SUMMARIZATION,
    dataset_paths=[
        "./datasets/summarization/set_a.json",
        "./datasets/summarization/set_b.json",        # 多個 dataset 會依序執行
    ],
    config=TaskConfig(task_type=TaskType.SUMMARIZATION, llm=llm, llm_params={...}),
    evaluate_kwargs={"probability_normalize": True},
    name="Summarization-Qwen3-14B",
))

results = pipeline.run(batch_size=5)
pipeline.export_report("./output/pipeline_report.json")

完整範例：examples/llm_evals/pipeline_example.py

PipelineStep 參數說明

參數	型別	說明
`task_type`	`TaskType`	任務類型（必填）
`dataset_paths`	`str \| List[str]`	資料集路徑，支援單一字串或多個路徑的 list（必填）
`config`	`TaskConfig`	對應任務的 TaskConfig（必填）
`evaluate_kwargs`	`dict`	透傳給 `async_evaluate()` 的任務特定參數，如 `probability_normalize`、`top_k`、`use_single_prompt` 等（選填）
`name`	`str`	步驟名稱，顯示於 log 與 report（選填，預設為 task_type.value）

執行摘要報告格式

export_report() 輸出的 JSON 結構：

{
  "generated_at": "2026-03-16T10:00:00",
  "total_steps": 2,
  "success": 1,
  "partial": 1,
  "failed": 0,
  "total_elapsed_seconds": 120.5,
  "steps": [
    {
      "step": 1,
      "name": "QA-Qwen3-14B",
      "task_type": "qa",
      "dataset_paths": ["./datasets/qa/example_qa.json"],
      "status": "success",
      "total_elapsed_seconds": 45.2,
      "datasets": [
        {
          "dataset_path": "./datasets/qa/example_qa.json",
          "status": "success",
          "elapsed_seconds": 45.2,
          "result_path": "output/qa/result.json",
          "error": null
        }
      ]
    }
  ]
}

step 層級的 status 說明：success（全部成功）、partial（部分成功）、error（全部失敗）。

各自使用方式

所有任務均透過 TaskConfig + 對應 Task 類別啟動，並以 asyncio.run() 執行非同步評估。

多選題問答（QA）

import asyncio
from src.api.async_llm_client import AsyncLLMChat
from src.tasks.base_task import TaskConfig, TaskType
from src.tasks.qa_task import QATask

async_llm = AsyncLLMChat(model="Qwen3-14B", config_path="./config/models.yaml")

config = TaskConfig(
    task_type=TaskType.QA,
    llm=async_llm,
    llm_params={'temperature': 0.8, 'max_tokens': 500, 'top_p': 0.8},
    llm_extra_body={"chat_template_kwargs": {"enable_thinking": False}}
)
task = QATask(config)
asyncio.run(task.async_evaluate(dataset_path="./datasets/qa/example_qa.json", batch_size=2))

摘要評估（Summarization / G-Eval）

import asyncio
from src.api.async_llm_client import AsyncLLMChat
from src.tasks.base_task import TaskConfig, TaskType
from src.tasks.summarization_task import SummarizationTask

async_llm = AsyncLLMChat(model="Qwen3-14B", config_path="./config/models.yaml")

config = TaskConfig(
    task_type=TaskType.SUMMARIZATION,
    llm=async_llm,
    llm_params={'temperature': 2, 'max_tokens': 30, 'top_p': 1},
    llm_extra_body={"chat_template_kwargs": {"enable_thinking": False}}
)
task = SummarizationTask(config)
asyncio.run(task.async_evaluate(
    dataset_path="./datasets/summarization/sample_summary.json",
    batch_size=2,
    probability_normalize=True
))

評估指標：Relevance、Coherence、Consistency、Fluency

RAG 檢索評估

import asyncio
from src.api.embedding_rerank_client import EmbeddingModel, RerankingModel
from src.tasks.base_task import TaskConfig, TaskType
from src.tasks.rag.rag_task import RAGTask

emb = EmbeddingModel(embedding_model="bge-m3", config_path='./config/models.yaml', use_async=True)
rerank = RerankingModel(reranking_model="bge-reranker-large", config_path='./config/models.yaml', use_async=True)

config = TaskConfig(
    task_type=TaskType.RAG,
    embedding_model=emb,
    reranking_model=rerank,
    custom_params={
        "embedding_dim": 1024,
        "rrf_k": 60,
        "bm25_language": "zh"  # "en" 或 "zh"
    }
)
task = RAGTask(config)
asyncio.run(task.async_evaluate(dataset_path="./datasets/rag/example_rag.json", batch_size=10, top_k=5))

工具呼叫（Tool Calling）

自訂資料集：

import asyncio
from src.api.async_llm_client import AsyncLLMChat
from src.tasks.base_task import TaskConfig, TaskType
from src.tasks.tool_calling.tool_calling_task import ToolCallingTask

async_llm = AsyncLLMChat(model="Qwen3-14B", config_path="./config/models.yaml")
config = TaskConfig(
    task_type=TaskType.TOOLCALLING,
    llm=async_llm,
    llm_params={'temperature': 0.8, 'max_tokens': 500, 'top_p': 0.8},
    llm_extra_body={"chat_template_kwargs": {"enable_thinking": False}}
)
task = ToolCallingTask(config)
asyncio.run(task.async_evaluate(dataset_path="./datasets/tool_calling/tool_calling_example.json", batch_size=5))

BFCL 格式資料集：

from src.tasks.base_task import TaskConfig, TaskType, TaskDatasetType

config = TaskConfig(
    task_type=TaskType.TOOLCALLING,
    dataset_type=TaskDatasetType.BCFL,   # 指定 BFCL 格式
    llm=async_llm,
    ...
)
task = ToolCallingTask(config)
asyncio.run(task.async_evaluate(
    dataset_path="./bfcl_data/BFCL_v3_exec_parallel_multiple.json",
    batch_size=5,
    folder_name="Qwen3-14B_run1"
))

查核價值判斷（Check Worthiness）

import asyncio
from src.api.async_llm_client import AsyncLLMChat
from src.tasks.base_task import TaskConfig, TaskType
from src.tasks.check_worthiness_task import CheckWorthinessTask

async_llm = AsyncLLMChat(model="Qwen3-14B", config_path="config/models.yaml")
config = TaskConfig(
    task_type=TaskType.CHECKWORTHINESS,
    llm=async_llm,
    llm_params={'temperature': 0, 'max_tokens': 100, 'top_p': 1}
)
task = CheckWorthinessTask(config)
asyncio.run(task.async_evaluate(
    dataset_path="datasets/factcheck/factcheck_claim_checkworthiness.json",
    batch_size=10,
    use_single_prompt=True
))

聲明證據立場（Claim Evidence Stance）

支援 LLM 和 NLI（外部推論服務）兩種模式：

import asyncio
from src.tasks.base_task import TaskConfig, TaskType
from src.tasks.claim_evidence_stance_task import ClaimEvidenceStanceTask

# NLI 模式
config = TaskConfig(
    task_type=TaskType.CLAIMEVIDENCESTANCE,
    custom_params={
        'use_nli': True,
        'nli_url': "http://your-nli-service/infer/xlm-roberta-large-xnli",
        'nli_timeout': 30.0,
        'nli_threshold': 0.8
    }
)

# LLM 模式
# config = TaskConfig(task_type=TaskType.CLAIMEVIDENCESTANCE, llm=async_llm, custom_params={'use_nli': False}, ...)

task = ClaimEvidenceStanceTask(config)
asyncio.run(task.async_evaluate(
    dataset_path="datasets/factcheck/factcheck_claim_evidence_stance.json",
    batch_size=5
))

更多範例請參考 examples/llm_evals/。

專案結構

llm-evals/
├── src/
│   ├── api/
│   │   ├── llm_client.py               # 同步 LLM 客戶端 (LLMChat)
│   │   ├── async_llm_client.py         # 非同步 LLM 客戶端 (AsyncLLMChat)
│   │   └── embedding_rerank_client.py  # Embedding / Reranking 客戶端
│   ├── tasks/
│   │   ├── base_task.py                # 抽象基礎類別 (BaseTask, TaskConfig, TaskType)
│   │   ├── qa_task.py                  # 多選題問答
│   │   ├── summarization_task.py       # 摘要品質評估
│   │   ├── fact_extract_task.py        # 事實抽取
│   │   ├── qa_generate_task.py         # 問答對生成評估
│   │   ├── faq_response_task.py        # FAQ 回應評估
│   │   ├── check_worthiness_task.py    # 查核價值判斷
│   │   ├── claim_evidence_stance_task.py # 聲明證據立場
│   │   ├── generate_claims.py          # 生成聲明
│   │   ├── generate_truths.py          # 生成真相
│   │   ├── rag/
│   │   │   └── rag_task.py             # RAG 檢索評估
│   │   └── tool_calling/
│   │       └── tool_calling_task.py    # 工具呼叫評估
│   ├── prompts/                        # 各任務的 Prompt 模板
│   ├── utils/
│   │   └── tool_process.py             # 工具呼叫資料處理工具
│   └── pipeline.py                     # EvalPipeline 多任務評估流水線
├── examples/
│   └── llm_evals/                      # 各任務的範例腳本
├── datasets/                           # 資料集（依任務分類）
├── bfcl_data/                          # BFCL benchmark 資料集
├── config/
│   ├── example_models.yaml             # 設定檔範本
│   └── models.yaml                     # 實際使用的設定檔（需自行建立）
└── pyproject.toml

TaskConfig 參數說明

參數	型別	說明
`task_type`	`TaskType`	任務類型（必填）
`llm`	`AsyncLLMChat`	非同步 LLM 客戶端
`llm_params`	`dict`	LLM 推論參數（temperature、max_tokens 等）
`llm_extra_body`	`dict`	傳遞給 API 的額外參數（如 `enable_thinking`）
`embedding_model`	`EmbeddingModel`	Embedding 模型（RAG 任務使用）
`reranking_model`	`RerankingModel`	Reranking 模型（RAG 任務使用）
`custom_params`	`dict`	任務特定的自訂參數
`dataset_type`	`TaskDatasetType`	資料集格式（`DEFAULT` 或 `BCFL`）

License

This project is licensed under the MIT License.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

llm-evals

支援的任務

安裝

設定模型 Config

EvalPipeline：多任務批次評估

快速開始

PipelineStep 參數說明

執行摘要報告格式

各自使用方式

多選題問答（QA）

摘要評估（Summarization / G-Eval）

RAG 檢索評估

工具呼叫（Tool Calling）

查核價值判斷（Check Worthiness）

聲明證據立場（Claim Evidence Stance）

專案結構

TaskConfig 參數說明

License

FilesExpand file tree

README_zh-CN.md

Latest commit

History

README_zh-CN.md

File metadata and controls

llm-evals

支援的任務

安裝

設定模型 Config

EvalPipeline：多任務批次評估

快速開始

PipelineStep 參數說明

執行摘要報告格式

各自使用方式

多選題問答（QA）

摘要評估（Summarization / G-Eval）

RAG 檢索評估

工具呼叫（Tool Calling）

查核價值判斷（Check Worthiness）

聲明證據立場（Claim Evidence Stance）

專案結構

TaskConfig 參數說明

License