Hướng dẫn cho lập trình viên

Clausa

Một sản phẩm của Belumind · Văn bản hành chính & pháp luật

Đọc nội dung quyết định, công văn, nghị định, thông tư — lấy thẳng từ bước OCR của bạn, hay văn bản gõ không dấu — và lấy ra cơ quan ban hành, số ký hiệu, ngày ban hành, người ký và các văn bản làm căn cứ. Clausa còn cho thấy các văn bản liên quan với nhau thế nào: văn bản nào dẫn chiếu, thay thế hay bãi bỏ văn bản nào. Công cụ đủ nhỏ để chạy trên máy chủ của chính bạn, nên văn bản không bao giờ rời khỏi tổ chức.

Địa chỉ cho phần mềm của bạn (API)

https://api2.belumind.com/clausa

Địa chỉ cho trợ lý AI (MCP)

https://mcp2.belumind.com/clausa

Độ chính xác (thông tin / liên kết): 90,0 / 81,2
Máy chủ mạnh (GPU A100): 0,20 giây / trang
Máy chủ thường (CPU Xeon): 5,09 giây / trang
Kích thước: < 0,5 tỷ tham số

Key truy cập

Mọi yêu cầu đều gửi kèm hai thứ: API key cho sản phẩm này, tạo trong trang quản lý ở mục API key, và access token của người dùng đang đăng nhập sở hữu key đó. Token có hạn 15 phút, nên hãy làm mới và gửi token mới. Key tạo cho sản phẩm khác sẽ nhận lỗi 403 — nhờ vậy, bạn có thể giao cho trợ lý AI một key chỉ dùng được đúng một công cụ và không gì khác.

Trợ lý AI gửi cùng hai header đó khi kết nối tới địa chỉ ở trên.

clausa:extract

Cách gửi key

X-API-Key: bm_live_7f3c…
Authorization: Bearer eyJhbGciOi…
Content-Type: application/json

POST/v1/extract/schemaclausa:extract

Đọc thông tin chính của một văn bản

Gửi nội dung một văn bản hành chính — Clausa không mở PDF hay ảnh, nên hãy chạy OCR trước — và nhận lại số ký hiệu, cơ quan ban hành, ngày ban hành (dạng `YYYY-MM-DD`), người ký, chức vụ người ký và các văn bản làm căn cứ. Lược đồ có sẵn `administrative_document` gồm các thông tin này; `GET /v1/schemas` (MCP: `list_schemas`) liệt kê lược đồ cùng mọi trường. Trường không tìm thấy được trả về rỗng chứ không đoán, và `warnings` nêu trường bắt buộc nào còn thiếu. Văn bản dài hơn 20.000 ký tự hãy gửi tới `POST /v1/jobs/schema`.

Công cụ cho trợ lý AIextract_document_fields

Nội dung cần gửi

textstringbắt buộc: Nội dung văn bản, UTF-8 — ví dụ kết quả từ bước OCR của bạn.
schema_namestringtuỳ chọn: Một lược đồ có sẵn trong `GET /v1/schemas`, ví dụ `administrative_document`. Gửi trường này hoặc `schema` — REST API không có giá trị mặc định, nên thiếu cả hai sẽ trả lỗi 422. (Công cụ MCP mặc định dùng `administrative_document`.)
schemaobjecttuỳ chọn: Các trường của riêng bạn thay cho lược đồ có sẵn: mỗi trường nêu một nhãn và, nếu cần, một quan hệ bắt buộc. `GET /v1/examples` có bốn ví dụ. Gửi trường này hoặc `schema_name`.
postprocessbooleantuỳ chọn: Làm sạch văn bản OCR trước khi đọc — bỏ dấu chữ ký số, logo và dòng lặp, sửa QD thành QĐ, ghép người ký với chức vụ. Mặc định bật; mọi thay đổi được liệt kê trong `postprocess.edits`.
detailbooleantuỳ chọn: Trả thêm các ứng viên, thực thể và quan hệ gốc của từng trường, cùng văn bản đã làm sạch. Dùng khi gỡ lỗi.

Kết quả nhận về

200 OKThành công. Bạn nhận về đúng như ví dụ.
400 Bad RequestNội dung bạn gửi bị sai hoặc thiếu. Câu trả lời cho biết phần nào.
401 UnauthorizedThiếu API key hoặc access token, gõ sai hoặc không còn hiệu lực. Access token hết hạn sau 15 phút — hãy làm mới và gửi token mới.
403 ForbiddenKey hợp lệ nhưng được tạo cho sản phẩm khác.
402 Payment RequiredTài khoản đã hết credit. Mua thêm trong trang quản lý, hoặc bật tự động nạp.
429 Too Many RequestsGửi quá nhiều trong thời gian ngắn, hoặc key đã chạm hạn mức tháng đặt cho nó. Chờ đúng số giây trong `Retry-After` rồi thử lại.
500 Internal Server ErrorCó lỗi phía chúng tôi. Gửi lại cùng yêu cầu là an toàn.
503 Service UnavailableHàng đợi đã đầy, hoặc không kết nối được trang quản lý để kiểm tra key. Thử lại sau ít phút.

Bạn gửi

curl -X POST https://api2.belumind.com/clausa/v1/extract/schema \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "ỦY BAN NHÂN DÂN TỈNH THANH VÂN\nSố: 1482/QD-UBND\nThanh Vân, ngày 18 tháng 3 năm 2026\nQUYẾT ĐỊNH\nVề việc ban hành Quy chế lưu trữ hồ sơ điện tử\nCăn cứ Luật Lưu trữ ngày 21 tháng 6 năm 2024;\nCăn cứ Nghị định số 118/2024/NĐ-CP;\n…\nKT. CHỦ TỊCH\nPHÓ CHỦ TỊCH\nTrần Minh Khải",
  "schema_name": "administrative_document"
}'

Bạn nhận về

application/json200 OK

{
  "result": {
    "document_number": "1482/QĐ-UBND",
    "issuing_authority": "ỦY BAN NHÂN DÂN TỈNH THANH VÂN",
    "issue_date": "2026-03-18",
    "signer": "Trần Minh Khải",
    "signer_title": "Phó Chủ tịch",
    "legal_bases": [
      "Luật Lưu trữ",
      "Nghị định số 118/2024/NĐ-CP"
    ]
  },
  "warnings": [],
  "device": "mps",
  "seconds": 0.59,
  "postprocess": {
    "lines_removed": 0,
    "edits": [
      {
        "field": "document_number",
        "before": "1482/QD-UBND",
        "after": "1482/QĐ-UBND",
        "reason": "document_type_code"
      },
      {
        "field": "signer_title",
        "before": "Phó chủ tịch",
        "after": "Phó Chủ tịch",
        "reason": "dictionary"
      }
    ]
  }
}

Thử ngay

Chế độ ví dụ

API keyAccess tokenNội dung cần gửi

POST https://api2.belumind.com/clausa/v1/extract/schema

Nền tảng đang trong giai đoạn truy cập sớm, nên ô này hiển thị câu trả lời mẫu thay vì liên hệ dịch vụ thật. Hãy xin chúng tôi một key và chính ô này sẽ gửi yêu cầu thật.

POST/v1/extractclausa:extract

Tìm tên, ngày và liên kết giữa chúng

Nêu loại thông tin cần tìm — người, chức vụ, tổ chức, ngày, văn bản — và liên kết giữa chúng, như ai giữ chức gì hay quyết định nào thay thế quyết định nào. Mỗi thực thể trả về kèm vị trí trong văn bản và mức độ chắc chắn; mỗi liên kết trỏ tới hai thực thể theo id. Clausa được huấn luyện trên các nhãn trong `GET /v1/labels`; nhãn khác vẫn dùng được nhưng kém chính xác hơn. Thêm `?download=true` để nhận kết quả dạng tệp JSON. `POST /v1/extract/batch` nhận nhiều yêu cầu như vậy cùng lúc, trong `items`, và đọc lần lượt từng yêu cầu.

Công cụ cho trợ lý AIextract_entities

Nội dung cần gửi

textstringbắt buộc: Nội dung cần đọc, UTF-8. Văn bản dài được tự động chia nhỏ.
entitiesstring[]bắt buộc: Các nhãn cần tìm, tiếng Việt có dấu — ví dụ `người`, `chức vụ`, `tổ chức`, `ngày`.
relationsstring[]tuỳ chọn: Các liên kết cần tìm giữa thực thể, như `giữ chức` hay `thay thế`. Có thể để trống.
thresholdnumbertuỳ chọn: Mức chắc chắn thấp nhất, 0–1, để giữ một thực thể. Mặc định theo ngưỡng của từng nhãn (0,5).
relation_thresholdnumbertuỳ chọn: Mức chắc chắn thấp nhất, 0–1, để giữ một liên kết. Mặc định 0,5.
max_words_per_chunkintegertuỳ chọn: Độ dài tối đa, tính bằng từ, của mỗi phần khi chia văn bản dài trước khi đọc, 10–200. Mặc định 40 — mức cho kết quả tốt nhất khi đo.

Kết quả nhận về

200 OKThành công. Bạn nhận về đúng như ví dụ.
400 Bad RequestNội dung bạn gửi bị sai hoặc thiếu. Câu trả lời cho biết phần nào.
401 UnauthorizedThiếu API key hoặc access token, gõ sai hoặc không còn hiệu lực. Access token hết hạn sau 15 phút — hãy làm mới và gửi token mới.
403 ForbiddenKey hợp lệ nhưng được tạo cho sản phẩm khác.
402 Payment RequiredTài khoản đã hết credit. Mua thêm trong trang quản lý, hoặc bật tự động nạp.
429 Too Many RequestsGửi quá nhiều trong thời gian ngắn, hoặc key đã chạm hạn mức tháng đặt cho nó. Chờ đúng số giây trong `Retry-After` rồi thử lại.
500 Internal Server ErrorCó lỗi phía chúng tôi. Gửi lại cùng yêu cầu là an toàn.
503 Service UnavailableHàng đợi đã đầy, hoặc không kết nối được trang quản lý để kiểm tra key. Thử lại sau ít phút.

Bạn gửi

curl -X POST https://api2.belumind.com/clausa/v1/extract \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Bổ nhiệm ông Nguyễn Văn An, Phó Giám đốc Sở Tài chính tỉnh Nghệ An, giữ chức Giám đốc Sở Tài chính tỉnh Nghệ An kể từ ngày 01 tháng 3 năm 2024.",
  "entities": [
    "người",
    "chức vụ",
    "tổ chức",
    "ngày"
  ],
  "relations": [
    "giữ chức",
    "thuộc tổ chức"
  ]
}'

Bạn nhận về

application/json200 OK

{
  "entities": [
    {
      "id": "e1",
      "text": "Nguyễn Văn An",
      "label": "người",
      "start": 13,
      "end": 26,
      "score": 0.9629
    },
    {
      "id": "e2",
      "text": "Phó Giám đốc",
      "label": "chức vụ",
      "start": 28,
      "end": 40,
      "score": 0.875
    },
    {
      "id": "e3",
      "text": "Sở Tài chính tỉnh Nghệ An",
      "label": "tổ chức",
      "start": 41,
      "end": 66,
      "score": 0.7334
    },
    {
      "id": "e4",
      "text": "Giám đốc",
      "label": "chức vụ",
      "start": 77,
      "end": 85,
      "score": 0.7603
    },
    {
      "id": "e5",
      "text": "Sở Tài chính tỉnh Nghệ An",
      "label": "tổ chức",
      "start": 86,
      "end": 111,
      "score": 0.7329
    },
    {
      "id": "e6",
      "text": "ngày 01 tháng 3 năm 2024",
      "label": "ngày",
      "start": 118,
      "end": 142,
      "score": 0.9536
    }
  ],
  "relations": [
    {
      "head": "e1",
      "relation": "giữ chức",
      "tail": "e2",
      "score": 0.6558,
      "head_text": "Nguyễn Văn An",
      "tail_text": "Phó Giám đốc"
    },
    {
      "head": "e1",
      "relation": "thuộc tổ chức",
      "tail": "e3",
      "score": 0.8726,
      "head_text": "Nguyễn Văn An",
      "tail_text": "Sở Tài chính tỉnh Nghệ An"
    },
    {
      "head": "e1",
      "relation": "giữ chức",
      "tail": "e4",
      "score": 0.8149,
      "head_text": "Nguyễn Văn An",
      "tail_text": "Giám đốc"
    }
  ],
  "meta": {
    "device": "mps",
    "chunks": 1,
    "max_words_per_chunk": 40,
    "entity_labels_queried": [
      "người",
      "chức vụ",
      "tổ chức",
      "ngày"
    ],
    "relation_labels_queried": [
      "giữ chức",
      "thuộc tổ chức"
    ],
    "seconds": 0.687,
    "warnings": []
  }
}

Thử ngay

Chế độ ví dụ

API keyAccess tokenNội dung cần gửi

POST https://api2.belumind.com/clausa/v1/extract

POST/v1/jobs/schemaclausa:extract

Gửi văn bản dài để đọc trong nền

Dành cho văn bản dài hơn 20.000 ký tự, tối đa 1.000.000. Nhận cùng nội dung như `POST /v1/extract/schema` và trả ngay id của tác vụ; kiểm tra `GET /v1/jobs/{job_id}` tới khi `status` là `done`. `POST /v1/jobs/extract` làm tương tự cho `POST /v1/extract`.

Công cụ cho trợ lý AIsubmit_job

Nội dung cần gửi

textstringbắt buộc: Nội dung văn bản, UTF-8, tối đa 1.000.000 ký tự.
schema_namestringtuỳ chọn: Một lược đồ có sẵn, ví dụ `administrative_document`. Các trường khác của `POST /v1/extract/schema` cũng dùng được ở đây.

Kết quả nhận về

202 AcceptedĐã nhận — đang chờ đến lượt xử lý.
400 Bad RequestNội dung bạn gửi bị sai hoặc thiếu. Câu trả lời cho biết phần nào.
401 UnauthorizedThiếu API key hoặc access token, gõ sai hoặc không còn hiệu lực. Access token hết hạn sau 15 phút — hãy làm mới và gửi token mới.
403 ForbiddenKey hợp lệ nhưng được tạo cho sản phẩm khác.
402 Payment RequiredTài khoản đã hết credit. Mua thêm trong trang quản lý, hoặc bật tự động nạp.
429 Too Many RequestsGửi quá nhiều trong thời gian ngắn, hoặc key đã chạm hạn mức tháng đặt cho nó. Chờ đúng số giây trong `Retry-After` rồi thử lại.
500 Internal Server ErrorCó lỗi phía chúng tôi. Gửi lại cùng yêu cầu là an toàn.
503 Service UnavailableHàng đợi đã đầy, hoặc không kết nối được trang quản lý để kiểm tra key. Thử lại sau ít phút.

Bạn gửi

curl -X POST https://api2.belumind.com/clausa/v1/jobs/schema \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "ỦY BAN NHÂN DÂN TỈNH THANH VÂN\nSố: 1482/QD-UBND\n…",
  "schema_name": "administrative_document"
}'

Bạn nhận về

application/json202 Accepted

{
  "id": "8c41f2a0d3b94e6f9a1c5b7e2d40f318",
  "kind": "schema",
  "status": "queued",
  "queue_position": 1,
  "created_at": 1774512000.5,
  "started_at": null,
  "finished_at": null,
  "progress": {
    "chunks_done": 0,
    "chunks_total": null
  },
  "error": null,
  "result": null
}

Thử ngay

Chế độ ví dụ

API keyAccess tokenNội dung cần gửi

POST https://api2.belumind.com/clausa/v1/jobs/schema

GET/v1/jobs/{job_id}clausa:extract

Xem một tác vụ chạy nền

Cho biết tác vụ đang ở đâu — `queued`, `running`, `done`, `failed` hay `cancelled` — và đã đọc được bao nhiêu phần. Khi `done`, `result` chứa đúng JSON mà endpoint đồng bộ sẽ trả về. `DELETE /v1/jobs/{job_id}` huỷ tác vụ còn đang chờ.

Công cụ cho trợ lý AIget_job

Tuỳ chọn trong địa chỉ

job_idstringbắt buộc: `id` do `POST /v1/jobs/schema` hoặc `POST /v1/jobs/extract` trả về.

Kết quả nhận về

200 OKThành công. Bạn nhận về đúng như ví dụ.
400 Bad RequestNội dung bạn gửi bị sai hoặc thiếu. Câu trả lời cho biết phần nào.
401 UnauthorizedThiếu API key hoặc access token, gõ sai hoặc không còn hiệu lực. Access token hết hạn sau 15 phút — hãy làm mới và gửi token mới.
403 ForbiddenKey hợp lệ nhưng được tạo cho sản phẩm khác.
402 Payment RequiredTài khoản đã hết credit. Mua thêm trong trang quản lý, hoặc bật tự động nạp.
429 Too Many RequestsGửi quá nhiều trong thời gian ngắn, hoặc key đã chạm hạn mức tháng đặt cho nó. Chờ đúng số giây trong `Retry-After` rồi thử lại.
500 Internal Server ErrorCó lỗi phía chúng tôi. Gửi lại cùng yêu cầu là an toàn.
503 Service UnavailableHàng đợi đã đầy, hoặc không kết nối được trang quản lý để kiểm tra key. Thử lại sau ít phút.

Bạn gửi

curl -X GET https://api2.belumind.com/clausa/v1/jobs/{job_id} \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN"

Bạn nhận về

application/json200 OK

{
  "id": "8c41f2a0d3b94e6f9a1c5b7e2d40f318",
  "kind": "schema",
  "status": "done",
  "queue_position": null,
  "created_at": 1774512000.5,
  "started_at": 1774512001.1,
  "finished_at": 1774512019.8,
  "progress": {
    "chunks_done": 212,
    "chunks_total": 212
  },
  "error": null,
  "result": {
    "result": {
      "document_number": "1482/QĐ-UBND",
      "issuing_authority": "ỦY BAN NHÂN DÂN TỈNH THANH VÂN",
      "issue_date": "2026-03-18",
      "signer": "Trần Minh Khải",
      "signer_title": "Phó Chủ tịch",
      "legal_bases": [
        "Luật Lưu trữ",
        "Nghị định số 118/2024/NĐ-CP"
      ]
    },
    "warnings": [],
    "device": "mps",
    "seconds": 18.7
  }
}

Thử ngay

Chế độ ví dụ

API keyAccess token

job_id

GET https://api2.belumind.com/clausa/v1/jobs/

GET/v1/labelsclausa:extract

Danh sách nhãn Clausa nắm vững nhất

Các nhãn thực thể và liên kết mà Clausa được huấn luyện — dùng chúng trong `POST /v1/extract` để chính xác nhất. Khi bạn hỏi một liên kết, Clausa cũng tìm các nhãn trong `tail_default` của nó. Không cần khoá, giống `GET /v1/schemas` và `GET /v1/examples`.

Công cụ cho trợ lý AIlist_labels

Kết quả nhận về

200 OKThành công. Bạn nhận về đúng như ví dụ.
400 Bad RequestNội dung bạn gửi bị sai hoặc thiếu. Câu trả lời cho biết phần nào.
401 UnauthorizedThiếu API key hoặc access token, gõ sai hoặc không còn hiệu lực. Access token hết hạn sau 15 phút — hãy làm mới và gửi token mới.
403 ForbiddenKey hợp lệ nhưng được tạo cho sản phẩm khác.
402 Payment RequiredTài khoản đã hết credit. Mua thêm trong trang quản lý, hoặc bật tự động nạp.
429 Too Many RequestsGửi quá nhiều trong thời gian ngắn, hoặc key đã chạm hạn mức tháng đặt cho nó. Chờ đúng số giây trong `Retry-After` rồi thử lại.
500 Internal Server ErrorCó lỗi phía chúng tôi. Gửi lại cùng yêu cầu là an toàn.
503 Service UnavailableHàng đợi đã đầy, hoặc không kết nối được trang quản lý để kiểm tra key. Thử lại sau ít phút.

Bạn gửi

curl -X GET https://api2.belumind.com/clausa/v1/labels \
  -H "X-API-Key: $BELUMIND_API_KEY" \
  -H "Authorization: Bearer $BELUMIND_ACCESS_TOKEN"

Bạn nhận về

application/json200 OK

{
  "entity_labels": [
    "văn bản",
    "số hiệu văn bản",
    "tổ chức",
    "người",
    "chức vụ",
    "ngày",
    "địa điểm",
    "điều khoản",
    "đối tượng áp dụng",
    "số lượng",
    "thời hạn",
    "giấy tờ"
  ],
  "relation_labels": [
    {
      "name": "ban hành bởi",
      "tail_default": [
        "tổ chức"
      ]
    },
    {
      "name": "ban hành ngày",
      "tail_default": [
        "ngày"
      ]
    },
    {
      "name": "giữ chức",
      "tail_default": [
        "chức vụ"
      ]
    },
    {
      "name": "thuộc tổ chức",
      "tail_default": [
        "tổ chức"
      ]
    },
    {
      "name": "thay thế",
      "tail_default": [
        "văn bản"
      ]
    },
    {
      "name": "bãi bỏ",
      "tail_default": [
        "văn bản"
      ]
    },
    {
      "name": "ký",
      "tail_default": [
        "văn bản",
        "số hiệu văn bản"
      ]
    }
  ]
}

Thử ngay

Chế độ ví dụ

API keyAccess token

GET https://api2.belumind.com/clausa/v1/labels

Dùng với trợ lý AI

Khi kết nối với trợ lý AI, Clausa giúp trợ lý đọc cả chồng văn bản hành chính và trả lời câu hỏi về quan hệ giữa chúng — quyết định nào thay thế quyết định nào, ai ký, dựa trên căn cứ nào — trích đúng thông tin thay vì kể lại nội dung. Vì Clausa chạy trên máy chủ của bạn, văn bản vẫn nằm trong tổ chức của bạn.

Bạn hỏi

“Những quyết định nào trong số này còn hiệu lực, và 1482/QĐ-UBND đã thay thế văn bản nào?”

Trợ lý sẽ

01Gửi nội dung từng văn bản cho Clausa
02Lần theo văn bản nào thay thế hay bãi bỏ văn bản nào
03Trả lời kèm số ký hiệu, người ký, và chỉ ra thông tin nào Clausa chưa chắc chắn

Cài đặt để dán vào trợ lý AI

{
  "mcpServers": {
    "clausa": {
      "url": "https://mcp2.belumind.com/clausa",
      "headers": {
        "X-API-Key": "bm_live_7f3c…",
        "Authorization": "Bearer eyJhbGciOi…"
      }
    }
  }
}

Khi có sự cố

Khi một yêu cầu thất bại, bạn nhận được một số lỗi tiêu chuẩn và một code ngắn để phần mềm của bạn xử lý, kèm một thông báo dễ hiểu cho người đọc. Mỗi yêu cầu có thể kèm Idempotency-Key, nên gửi lại sau sự cố phía chúng tôi là an toàn — việc sẽ không bị làm hai lần.

Lỗi trông như thế nào4xx / 5xx

{
  "error": {
    "code": "invalid_parameter",
    "message": "`url` must be a reachable http(s) URL.",
    "param": "url",
    "request_id": "req_4d91c0b7"
  }
}

Sẵn sàng dùng thật?

Trong giai đoạn truy cập sớm, ô "Thử ngay" hiển thị câu trả lời mẫu. Hãy cho chúng tôi biết bạn đang xây gì, chúng tôi sẽ cấp key cho bạn.