Cung cấp Phương thức Tùy chỉnh dưới dạng một API

Phương thức api của champollion cho phép bạn trỏ bất kỳ cặp dịch thuật nào đến một endpoint HTTP bên ngoài. Đây là cách bạn tích hợp các pipeline quá phức tạp đối với một prompt LLM đơn lẻ — các bộ phân tích hình thái học, bộ chuyển đổi trạng thái hữu hạn (FST), các chuỗi LLM nhiều bước, hoặc bất kỳ phương thức nghiên cứu tùy chỉnh nào bạn đã xây dựng.

Tại sao lại dùng Dịch vụ API?

Một số pipeline dịch thuật không thể chạy trong một chu kỳ yêu cầu-phản hồi (prompt-response) đơn giản:

Bước trong pipeline	Ví dụ
Phân tích cấu trúc hình thái	Chia các từ đa tổng hợp (polysynthetic) thành các hình vị trước khi dịch
Xác thực FST	Từ chối các kết quả đầu ra vi phạm quy tắc ngữ âm hoặc hình thái
Chuỗi LLM nhiều bước	Các chu kỳ Tạo → Xác minh → Sửa lỗi với các mô hình khác nhau
Tra cứu từ điển	Tham chiếu chéo một từ điển song ngữ được biên soạn kỹ lưỡng ở giữa pipeline
Sự tham gia của con người (Human-in-the-loop)	Đưa các bản dịch chưa chắc chắn vào hàng đợi để chuyên gia xem xét

Phương thức api coi pipeline của bạn như một hộp đen — champollion gửi các chuỗi nguồn, dịch vụ của bạn trả về các bản dịch. Những gì xảy ra bên trong hoàn toàn phụ thuộc vào bạn.

Kiến trúc

Thiết lập Dịch vụ của bạn

Dịch vụ API của bạn phải triển khai một endpoint duy nhất chấp nhận và trả về JSON:

Định dạng Yêu cầu (Request)

champollion gửi chính xác body JSON này (xem api.js):

POST /translate
Content-Type: application/json
Authorization: Bearer <CHAMPOLLION_API_KEY>

{
  "source_locale": "en",
  "target_locale": "crk",
  "method": "crk-coached-v1",
  "keys": {
    "greeting": "Hello, welcome to our app",
    "farewell": "Goodbye and thanks"
  }
}

Trường	Kiểu dữ liệu	Mô tả
source_locale	string	Mã ngôn ngữ nguồn BCP 47
target_locale	string	Mã ngôn ngữ đích BCP 47
method	string	Tên plugin hoặc "default"
keys	object	Bản đồ (Map) của key → chuỗi nguồn cần dịch

### Response Format

Your service must return a `translations` object. An optional `meta` object can include cost and diagnostic info:

```json
{
  "translations": {
    "greeting": "tânisi, pê-kîwêw ôta",
    "farewell": "ekosi mâka, kinanâskomitin"
  },
  "meta": {
    "model": "my-custom-pipeline/v1",
    "cost_usd": 0.0042,
    "method": "decompose-translate-validate"
  }
}

Field	Type	Required	Description
translations	object	✅	Map of key → translated string
meta	object	—	Optional metadata
meta.cost_usd	number	—	If present, displayed in champollion's output
errors	object	—	For partial success (HTTP 207): map of key → { message }

Minimal Express Server

import express from 'express';

const app = express();
app.use(express.json());

/**
 * champollion API contract:
 *
 * Request:  { source_locale, target_locale, method, keys: { "key": "source" } }
 * Response: { translations: { "key": "translated" }, meta: { ... } }
 */
app.post('/translate', async (req, res) => {
  const { source_locale, target_locale, method, keys } = req.body;

  const translations = {};

  for (const [key, source] of Object.entries(keys)) {
    // --- Your pipeline goes here ---
    // Step 1: Morphological decomposition
    const morphemes = await decompose(source, source_locale);

    // Step 2: LLM translation with context
    const draft = await llmTranslate(morphemes, target_locale);

    // Step 3: FST validation
    const validated = await fstValidate(draft, target_locale);

    // Step 4: Post-processing (orthography normalization, etc.)
    translations[key] = await postProcess(validated);
  }

  res.json({
    translations,
    meta: {
      model: 'my-custom-pipeline/v1',
      method: 'decompose-translate-validate',
    },
  });
});

app.listen(3001, () => {
  console.log('Translation API running on http://localhost:3001');
});

Configuring champollion

Point a translation pair at your running service in champollion.config.json:

{
  "inputLocale": "en",
  "pairs": {
    "en:crk": {
      "method": "api",
      "endpoint": "http://localhost:3001/translate",
      "register": "Formal Plains Cree. Use SRO orthography."
    }
  }
}

Then run sync as usual:

npx champollion sync

champollion will POST your source strings to the endpoint and write the returned translations to crk.json.

Case Study: Plains Cree Pipeline

:::info Under Development The Plains Cree pipeline described below is under active development and is not yet running in production. Details here reflect the current design direction and may change as the project evolves. :::

The arena project demonstrates this pattern. Its Plains Cree pipeline uses:

1. Morphological decomposition — Break polysynthetic Cree words into translatable morpheme chains
2. LLM translation — Context-enriched GPT-4o translation with coaching data (SRO orthography rules, register instructions)
3. FST validation — Finite-state transducer checks that outputs conform to Cree phonological rules
4. Confidence scoring — Each translation gets a confidence score based on FST pass rate and dictionary coverage

The entire pipeline runs as a single HTTP endpoint that champollion calls via the api method.

Running Evaluations

After translating, you can evaluate output quality using the harness directly:

# Clone the harness
git clone https://github.com/gamedaysuits/arena.git
cd arena
pip install -e .

# Run the evaluation against your method's output
mt-eval run --corpus data/edtekla-dev-v1.json --submit

This produces structured evaluation records with chrF++, BLEU, and exact match scores that can be used as regression baselines.

Authentication

If your API requires authentication, set the apiKey field or use an environment variable:

{
  "pairs": {
    "en:crk": {
      "method": "api",
      "endpoint": "https://my-mt-service.example.com/translate",
      "apiKey": "${CRK_API_KEY}"
    }
  }
}

Data Sovereignty & OCAP Principles

The api method is particularly important for Indigenous language communities. By self-hosting the translation pipeline, a community keeps full control over:

• Proprietary coaching data — register instructions, orthography rules, and domain glossaries never leave community infrastructure.
• Linguistic resources — curated dictionaries, FST grammars, and elder-verified translations remain under community ownership.
• Access policies — the community decides who can call the endpoint and under what terms.

This aligns with OCAP® principles (Ownership, Control, Access, Possession), ensuring that sensitive language data is governed by the community rather than a third-party platform.

mẹo

Combine the api method with a private deployment (e.g., a community-hosted VM or on-prem server) for the strongest data-sovereignty posture. See Support a Low-Resource Language for a full walkthrough.

Cost Estimation

The api method returns null for cost estimation by default — your service controls pricing. If you want to provide cost transparency, have your API return a cost field in the metadata:

{
  "translations": { "...": "..." },
  "metadata": {
    "cost": {
      "estimatedCost": 0.0042,
      "currency": "USD",
      "source": "my-service-pricing"
    }
  }
}

Thực hành Tốt nhất

1. Trả về chuỗi rỗng khi thất bại — Đừng trả về chuỗi nguồn dưới dạng một "bản dịch". Hãy trả về "" và cổng kiểm soát chất lượng (quality gate) của champollion sẽ phát hiện ra. Khóa (key) đó sẽ bị bỏ qua và được thử lại trong lần đồng bộ tiếp theo.
2. Bao gồm điểm tin cậy (confidence score) — Nếu pipeline của bạn có thể ước lượng chất lượng, hãy trả về thông tin đó trong metadata. Điều này giúp ích cho việc kiểm định chất lượng.
3. Triển khai kiểm tra trạng thái (health check) — Thêm một endpoint GET /health để champollion có thể xác minh kết nối trước khi bắt đầu một đợt đồng bộ lớn.
4. Giới hạn tốc độ (rate limit) một cách khéo léo — Nếu pipeline của bạn có giới hạn về băng thông, hãy trả về mã trạng thái 429. Hệ thống xử lý theo lô (batch) của champollion sẽ tự động giãn cách thời gian gửi yêu cầu.
5. Ghi nhật ký (log) mọi thứ — Các pipeline nhiều bước có thể gặp lỗi một cách âm thầm. Hãy ghi nhật ký đầu vào/đầu ra của từng bước để phục vụ việc gỡ lỗi (debugging).

Bản quyền

Mẫu phương thức api hoàn toàn mở — không có hạn chế nào về bản quyền đối với việc đóng gói pipeline dịch thuật của riêng bạn dưới dạng một dịch vụ HTTP. arena được cung cấp theo giấy phép MIT cho các triển khai tham khảo.

Xem thêm

• Phương thức Dịch thuật — tổng quan về mọi phương thức tích hợp sẵn (openai, google, api, v.v.)
• Đặc tả Plugin — schema đầy đủ cho champollion.config.json bao gồm các trường phương thức api
• Hỗ trợ Ngôn ngữ Nguồn lực Thấp — hướng dẫn toàn diện cho các ngôn ngữ thiếu thốn tài nguyên, bao gồm các nguyên tắc OCAP
• Kiến trúc — cách thức hoạt động của vòng lặp đồng bộ (sync loop), xử lý theo lô (batching) và điều phối phương thức (method dispatch) của champollion
• Đánh giá Dịch máy (MT Evaluation) — phương pháp đánh giá, các chỉ số và quy trình gửi lên bảng xếp hạng (leaderboard)
• Bảng xếp hạng Phương thức — bảng xếp hạng chất lượng trực tiếp giữa các phương thức và cặp ngôn ngữ