> ## Documentation Index
> Fetch the complete documentation index at: https://hyperlocalise.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# eval

> Thử nghiệm: Chạy các thử nghiệm chất lượng bản dịch và so sánh các báo cáo ứng viên với một đường cơ sở.

<Note>
  Tính năng này đang ở giai đoạn thử nghiệm. Cờ, hình dạng đầu ra và hành vi có thể thay đổi giữa các bản phát hành. Hãy sử dụng trong các quy trình làm việc được kiểm soát và cố định phiên bản trong CI.

  Lược đồ báo cáo và hành vi chấm điểm có thể thay đổi khi các quy trình đánh giá trưởng thành.
</Note>

Dùng các lệnh `eval` để đánh giá chất lượng bản dịch trên một bộ eval đại diện và áp dụng các ngưỡng chất lượng trong CI.

## Cách sử dụng

```bash theme={null}
hyperlocalise eval run --eval-set <path> [flags]
hyperlocalise eval compare --candidate <path> --baseline <path> [flags]
```

## chạy eval

Chạy một hoặc nhiều biến thể thí nghiệm trên bộ eval của bạn.

### Luồng đánh giá

```text theme={null}
eval set
  |
  v
expand experiment matrix
  |
  v
translate each case with each experiment
  |
  +--> heuristic lane
  |      - placeholder / ICU / tag checks
  |      - length / forbidden-term / locale checks
  |      - reference similarity
  |
  +--> judge lane (optional)
  |      - llm-rubric
  |      - factuality
  |      - g-eval
  |      - model-graded-closedqa
  |      - answer-relevance
  |      - context-faithfulness
  |      - context-recall
  |
  v
per-run result
  - quality.weightedAggregate
  - judgeAggregateScore
  - finalScore
  - decision
  |
  v
report aggregates
  - overall aggregate
  - byLocale
```

### Lệnh này làm gì

1. Tải bộ dữ liệu eval từ `--eval-set`.
2. Mở rộng các biến thể thử nghiệm từ tập dữ liệu `experiments` hoặc từ các hồ sơ, nhà cung cấp, mô hình và ghi đè prompt bạn đã chọn.
3. Thực thi mọi trường hợp đối với mọi biến thể thử nghiệm.
4. Chấm điểm mỗi bản dịch bằng làn heuristic tích hợp sẵn.
5. Tùy chọn thêm một làn đánh giá LLM khi bạn truyền cả `--eval-provider` và `--eval-model`.
6. Hòa giải chất lượng heuristic và điểm đánh giá thành công thành một `finalScore` cho mỗi lần chạy.
7. Ghi một báo cáo JSON khi bạn truyền `--output`.
8. In ra bảng tóm tắt ngắn gọn cho từng thí nghiệm.

### Cờ

* `--eval-set`: đường dẫn đến bộ dữ liệu đánh giá (`.yaml`, `.yml`) (bắt buộc)
* `--profile`: ghi đè tên hồ sơ (có thể lặp lại)
* `--provider`: ghi đè nhà cung cấp (có thể lặp lại)
* `--model`: ghi đè mô hình (có thể lặp lại)
* `--prompt-file`: ghi đè tệp prompt
* `--prompt`: ghi đè lời nhắc nội tuyến (loại trừ lẫn nhau với `--prompt-file`)
* `--eval-provider`: nhà cung cấp cho đánh giá LLM. Mặc định là `openai` khi yêu cầu đánh giá của giám khảo.
* `--eval-model`: mô hình để đánh giá LLM. Mặc định là `gpt-5.2` khi đánh giá của judge được yêu cầu.
* `--eval-prompt-file`: ghi đè tệp prompt đánh giá
* `--eval-prompt`: ghi đè lời nhắc đánh giá nội tuyến (loại trừ lẫn nhau với `--eval-prompt-file`)
* `--assertion`: xác định mệnh đề để chạy (có thể lặp lại). Giá trị được hỗ trợ: `llm-rubric`, `factuality`, `g-eval`, `model-graded-closedqa`, `answer-relevance`, `context-faithfulness`, `context-recall`
* `--baseline`: đường dẫn JSON của báo cáo đánh giá cơ sở để so sánh khi sử dụng `--interactive`
* `--output`: đường dẫn báo cáo đầu ra JSON

Chế độ đánh giá LLM được bật khi bạn yêu cầu đánh giá của judge, dù là một cách tường minh với `--eval-provider`, `--eval-model`, `--eval-prompt`, hoặc `--assertion`, hoặc một cách ngầm thông qua các khẳng định của judge trong eval-set.

Nếu yêu cầu đánh giá của judge và bạn bỏ qua provider/model, Hyperlocalise sẽ mặc định là `openai` và `gpt-5.2`.

Các cờ dịch của bạn vẫn giữ nguyên ý nghĩa hiện tại. Các cờ `--eval-*` chỉ kiểm soát làn phán xét.

Bản dịch tham chiếu là tùy chọn ở chế độ đánh giá LLM. Khi có, bộ đánh giá sẽ dùng chúng làm hướng dẫn về phong cách và giọng điệu.

Trong định dạng eval-set YAML, `reference` là trường phía đích thông thường. `assert` là tùy chọn.

Các `experiments` và `judge` ở cấp bộ dữ liệu là tùy chọn. Nếu bạn định nghĩa chúng trong YAML và không truyền ghi đè qua CLI, `eval run` sẽ sử dụng trực tiếp các cài đặt đó.

Nếu bạn truyền bất kỳ giá trị nào trong `--profile`, `--provider`, `--model` hoặc `--prompt`, ma trận thử nghiệm CLI sẽ ghi đè tập dữ liệu `experiments`.

Nếu bạn truyền bất kỳ giá trị nào trong số `--eval-provider`, `--eval-model`, `--eval-prompt` hoặc `--assertion`, thì các giá trị CLI đó sẽ ghi đè các trường `judge` của bộ dữ liệu.

Nếu bạn không truyền `--assertion`, thì khẳng định mặc định của judge là `llm-rubric`.

Các tên khẳng định không xác định sẽ thất bại ngay lập tức.

### Cách chấm điểm hoạt động

* `quality.weightedAggregate` là điểm heuristic tích hợp sẵn cho lần chạy.
* `judgeAggregateScore` là giá trị trung bình của các khẳng định phán quyết thành công cho lần chạy đó.
* `finalScore` là điểm số đã được đối chiếu được dùng để chẩn đoán trong báo cáo.
* `decision` là một kết quả thô cho lần chạy: `pass`, `review`, hoặc `fail`.

Các quy tắc đối chiếu hiện tại:

* lỗi dịch buộc `finalScore=0` và `decision=fail`
* lỗi cứng theo heuristic buộc `finalScore=0` và `decision=fail`
* khi làn đường của phán quyết không khả dụng, `finalScore` sẽ quay về điểm số heuristic
* khi cả hai làn đều khả dụng, `finalScore = 0.65 * heuristic + 0.35 * judge`

### Các trường của bảng tóm tắt

* `score`: điểm chất lượng trung bình có trọng số cho thử nghiệm
* `pass_rate`: số lần chạy thành công / tổng số lần chạy của thí nghiệm
* `placeholder_violations`: số lượng vi phạm toàn vẹn placeholder không thể chấp nhận được
* `latency_ms`: độ trễ trung bình của thí nghiệm

### Ví dụ

Chạy với các giá trị mặc định từ cấu hình của bạn và viết một báo cáo:

```bash theme={null}
hyperlocalise eval run \
  --eval-set ./evalsets/core.yaml \
  --output ./artifacts/eval-report.json
```

Chạy một ma trận các hồ sơ và ghi đè nhà cung cấp/mô hình:

```bash theme={null}
hyperlocalise eval run \
  --eval-set ./evalsets/core.yaml \
  --profile default \
  --profile fast \
  --provider openai \
  --provider anthropic \
  --model gpt-4.1-mini \
  --model claude-sonnet-4-5
```

Chạy với ghi đè tệp lời nhắc:

```bash theme={null}
hyperlocalise eval run \
  --eval-set ./evalsets/core.yaml \
  --prompt-file ./prompts/translation-eval.txt
```

Chạy với đánh giá LLM bằng cách sử dụng một prompt đánh giá nội tuyến:

```bash theme={null}
hyperlocalise eval run \
  --eval-set ./evalsets/core.yaml \
  --eval-provider openai \
  --eval-model gpt-4.1-mini \
  --eval-prompt "Score translation quality from 0.0 to 1.0 and explain briefly." \
  --output ./artifacts/eval-report.json
```

Chạy nhiều bộ đánh giá khẳng định trong một lượt:

```bash theme={null}
hyperlocalise eval run \
  --eval-set ./evalsets/core.yaml \
  --eval-provider openai \
  --eval-model gpt-4.1-mini \
  --assertion llm-rubric \
  --assertion factuality \
  --assertion g-eval \
  --assertion context-faithfulness \
  --output ./artifacts/eval-report.json
```

Chạy với đánh giá LLM bằng cách sử dụng một tệp prompt giám khảo:

```bash theme={null}
hyperlocalise eval run \
  --eval-set ./evalsets/core.yaml \
  --eval-provider anthropic \
  --eval-model claude-sonnet-4-5 \
  --eval-prompt-file ./prompts/eval-judge.txt \
  --output ./artifacts/eval-report.json
```

Sử dụng eval trong CI và kiểm tra báo cáo đã lưu:

```bash theme={null}
hyperlocalise eval run \
  --eval-set ./evalsets/release-gate.yaml \
  --provider openai \
  --model gpt-4.1-mini \
  --eval-provider openai \
  --eval-model gpt-4.1-mini \
  --assertion llm-rubric \
  --assertion factuality \
  --output ./artifacts/eval-candidate.json
```

### Ví dụ báo cáo

Bộ eval ví dụ:

```yaml theme={null}
experiments:
  - id: ollama-translategemma
    provider: ollama
    model: translategemma
  - id: ollama-lfm2-24b
    provider: ollama
    model: lfm2:24b
judge:
  provider: openai
  model: gpt-5.2
  assertions:
    - llm-rubric
    - factuality
tests:
  - id: checkout-cta
    vars:
      source: "Save account settings"
      context: "Primary CTA on the checkout settings page"
    locales:
      - locale: fr-FR
        reference: "Enregistrer les parametres du compte"
      - locale: de-DE
        reference: "Kontoeinstellungen speichern"
```

Ví dụ với các khẳng định rõ ràng:

```yaml theme={null}
experiments:
  - id: ollama-translategemma
    provider: ollama
    model: translategemma
tests:
  - id: checkout-cta
    vars:
      source: "Save account settings"
    assert:
      - type: judge.translation_quality
        threshold: 0.85
    locales:
      - locale: fr-FR
        reference: "Enregistrer les parametres du compte"
        assert:
          - type: contains
            value: "compte"
```

Chạy một bộ dữ liệu đã xác định sẵn các thử nghiệm Ollama:

```bash theme={null}
hyperlocalise eval run \
  --eval-set ./eval_dataset/article_001.yaml \
  --output ./artifacts/eval-report.json
```

Ví dụ rút gọn của JSON được ghi bởi `--output`:

```json theme={null}
{
  "aggregate": {
    "weightedScore": 0.812,
    "averageJudgeScore": 0.847,
    "finalScore": 0.824,
    "decisionCounts": {
      "pass": 18,
      "review": 3,
      "fail": 1
    },
    "byLocale": {
      "fr-FR": {
        "totalRuns": 10,
        "finalScore": 0.851
      },
      "de-DE": {
        "totalRuns": 12,
        "finalScore": 0.802
      }
    }
  },
  "experimentSummaries": [
    {
      "experimentId": "ollama-translategemma",
      "runCount": 11,
      "successfulRuns": 11,
      "averageJudgeScore": 0.838,
      "weightedScore": 0.806,
      "finalScore": 0.817,
      "decisionCounts": {
        "pass": 8,
        "review": 3
      }
    },
    {
      "experimentId": "ollama-lfm2-24b",
      "runCount": 11,
      "successfulRuns": 11,
      "averageJudgeScore": 0.856,
      "weightedScore": 0.819,
      "finalScore": 0.832,
      "decisionCounts": {
        "pass": 10,
        "review": 1
      }
    }
  ],
  "llmEvaluation": {
    "enabled": true,
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "assertions": [
      "llm-rubric",
      "factuality"
    ],
    "aggregateScore": 0.847,
    "averageScoreByName": {
      "judge:llm-rubric": 0.835,
      "judge:factuality": 0.859
    },
    "failedByName": {
      "judge:factuality": 1
    }
  },
  "runs": [
    {
      "caseId": "checkout.cta",
      "targetLocale": "fr-FR",
      "assertionResults": [
        {
          "type": "judge.translation_quality",
          "passed": true,
          "threshold": 0.85,
          "score": 0.88
        },
        {
          "type": "contains",
          "passed": true,
          "expected": "compte"
        }
      ],
      "judgeAggregateScore": 0.88,
      "quality": {
        "weightedAggregate": 0.91
      },
      "finalScore": 0.9,
      "decision": "pass",
      "judgeResults": {
        "judge:llm-rubric": {
          "score": 0.86
        },
        "judge:factuality": {
          "score": 0.9,
          "details": {
            "grounded": true,
            "hallucinations": []
          }
        }
      }
    }
  ]
}
```

Sử dụng báo cáo cấp cao nhất để theo dõi xu hướng và các bản ghi theo từng lần chạy để chẩn đoán:

* `experimentSummaries` là cách nhanh nhất để so sánh các biến thể mô hình theo `finalScore`, `weightedScore`, hoặc tổ hợp pass/review/fail.
* `aggregate.byLocale` là cách nhanh nhất để bản địa hóa các lỗi hồi quy.
* `llmEvaluation.averageScoreByName` cho thấy họ khẳng định nào đang kéo làn đường thẩm phán xuống.
* `assertionResults` cho biết liệu các kỳ vọng eval-set rõ ràng có được đáp ứng hay không.
* `judgeResults` chi tiết giải thích các lỗi cụ thể của câu khẳng định, chẳng hạn như ảo giác, các tuyên bố không được hỗ trợ hoặc thiếu các факт ngữ cảnh.

## đánh giá so sánh

So sánh báo cáo của ứng viên với báo cáo chuẩn.

Dùng lệnh này trong CI để ngăn chặn sự suy giảm chất lượng.

Quy trình vẫn giữ nguyên: hãy chạy `eval run` trước, rồi chạy `eval compare`.

### Cờ

* `--candidate`: đường dẫn JSON của báo cáo ứng viên (bắt buộc)
* `--baseline`: đường dẫn JSON của báo cáo cơ sở (bắt buộc)
* `--min-score`: điểm ứng viên tối thiểu
* `--max-regression`: mức suy giảm điểm số tối đa cho phép từ baseline đến candidate

### Hành vi CI

`eval compare` ưu tiên điểm tổng hợp LLM khi cả hai báo cáo đều bao gồm một điểm tổng hợp từ bộ đánh giá LLM có thể sử dụng. Nếu không, nó sẽ quay về điểm có trọng số theo heuristic.

Điều này có nghĩa là `eval compare` hiện đang phụ thuộc vào:

* Tổng hợp đánh giá của LLM khi đánh giá LLM được bật trong cả hai báo cáo
* tổng hợp heuristic khi không có tổng hợp phán đoán LLM khả dụng

Hiện tại nó chưa chặn theo `finalScore`.

Lệnh sẽ thoát với lỗi khi:

* điểm ứng viên thấp hơn `--min-score`, hoặc
* điểm hồi quy vượt quá `--max-regression`.

### Các ví dụ

So sánh báo cáo và chỉ in các giá trị tóm tắt:

```bash theme={null}
hyperlocalise eval compare \
  --candidate ./artifacts/eval-candidate.json \
  --baseline ./artifacts/eval-baseline.json
```

Thất bại CI nếu điểm của ứng viên giảm xuống dưới `0.82` hoặc bị giảm sút quá `0.02`:

```bash theme={null}
hyperlocalise eval compare \
  --candidate ./artifacts/eval-candidate.json \
  --baseline ./artifacts/eval-baseline.json \
  --min-score 0.82 \
  --max-regression 0.02
```

## Xem thêm

* [run](/commands/run)
* [status](/commands/status)
* [CI tự động hóa](/workflows/ci-automation)
* [Định dạng đầu ra](/reference/output-formats)