Hướng dẫn AI

Xây dựng quyết định LLM cục bộ nhanh, có kiểu dữ liệu với Rizzo Flow

Tìm hiểu cách cài đặt Rizzo Flow, chạy máy chủ llama.cpp cục bộ và nhận các quyết định boolean, lựa chọn, điểm số và số được định kiểu. Hướng dẫn này bao quát playground, API gốc và tương thích với Jev, các tùy chọn phần cứng, quyền từ chối quyết định, xử lý theo lô, giới hạn ngữ cảnh, bảo mật và các yếu tố thực tế về hiệu năng.

24 tháng 9, 2026Thời gian đọc khoảng 31 phút

Xây dựng quyết định LLM cục bộ nhanh, có kiểu dữ liệu với Rizzo Flow

Rizzo Flow là gì?

Rizzo Flow là một hệ thống mã nguồn mở, ưu tiên chạy cục bộ, chuyển đổi văn bản không có cấu trúc hoặc trạng thái JSON thành các quyết định có kiểu dữ liệu kèm xác suất. Thay vì yêu cầu mô hình ngôn ngữ tạo văn xuôi hoặc JSON từng token một, hệ thống đọc xác suất của mô hình đối với một tập hợp chữ cái trả lời bị giới hạn sau một lượt suy luận.

Thiết kế này hỗ trợ các quyết định như:

Câu trả lời boolean kèm xác suất của true.
Lựa chọn giữa các tùy chọn được đặt tên, với xác suất cho từng tùy chọn.
Điểm số theo các cấp độ tiêu chí được sắp xếp.
Ước tính số dựa trên các mốc đại diện.

Rizzo Flow chạy trên phần cứng của bạn thông qua llama.cpp. Hệ thống có thể sử dụng Apple Metal, NVIDIA CUDA, Vulkan, AMD ROCm, Intel SYCL hoặc CPU. Hệ thống cũng cung cấp giao diện HTTP tương thích với Jev, cho phép các ứng dụng tương thích trỏ đến một URL cục bộ thay vì dịch vụ lưu trữ.

Rizzo Flow là một dự án độc lập. Dự án tái hiện mẫu giao diện phía sau Jev, không tái hiện kiến trúc độc quyền hoặc quá trình huấn luyện của Jev. Các xác suất của hệ thống chưa được hiệu chuẩn, trừ khi bạn tự hiệu chuẩn chúng trên dữ liệu đại diện của mình.

Cách các quyết định không tạo token hoạt động

Với mỗi yêu cầu, Rizzo Flow đặt trạng thái ở đầu prompt và xử lý trạng thái một lần. Sau đó, các câu hỏi rẽ nhánh từ bộ nhớ đệm trạng thái dùng chung. Mỗi câu trả lời khả dĩ được ánh xạ tới một chữ cái viết hoa, và hệ thống chỉ đọc logits của các chữ cái được cho phép.

Trạng thái được chuyển thành văn bản và điền sẵn vào bộ nhớ đệm KV của mô hình.
Mỗi câu hỏi được biểu diễn dưới dạng một bài toán trắc nghiệm bị giới hạn.
Các câu hỏi dùng chung một trạng thái được đánh giá theo các lô nhỏ.
Logits của các câu trả lời được cho phép được chuyển thành xác suất bằng softmax.
Mã Python trả về dữ liệu boolean, lựa chọn, điểm số hoặc số đã được kiểm tra theo schema.

Không có vòng lặp giải mã, văn bản được lấy mẫu, phân tích đầu ra hoặc sửa JSON. Tuy nhiên, không tạo token nào không có nghĩa là không tốn tài nguyên tính toán: trạng thái và prompt câu hỏi vẫn cần được mô hình suy luận.

Tính năng chính

Vận hành hoàn toàn cục bộ: quá trình suy luận của mô hình diễn ra trên máy của bạn.
Kết quả có kiểu dữ liệu: ứng dụng nhận các giá trị có cấu trúc thay vì văn bản được tạo.
Phân phối xác suất: kết quả lựa chọn và điểm số hiển thị xác suất thay vì chỉ câu trả lời có argmax.
Bốn kiểu nguyên bản: boolean, choice, score và numeric.
Từ chối trả lời tùy chọn: API nguyên bản có thể báo cáo bằng chứng không đủ, sự không chắc chắn hoặc kết quả số nằm ngoài phạm vi.
Gộp theo trạng thái dùng chung: nhiều câu hỏi trong một yêu cầu sử dụng lại bộ nhớ đệm KV của trạng thái.
Các endpoint tương thích với Jev: các client hiện có có thể sử dụng /v1/systemone và /v1/models.
Mô hình ngữ cảnh dài: Spark-X2.5 hỗ trợ ngữ cảnh nguyên bản lên đến 1,048,576 token, mặc dù Rizzo Flow mặc định sử dụng 8,192 token cho mỗi câu hỏi.
Công cụ cục bộ: máy chủ bao gồm playground, tài liệu OpenAPI tương tác và bản minh họa Snake.

Điều kiện tiên quyết

Trước khi cài đặt Rizzo Flow, hãy đảm bảo bạn có:

Python 3.11 trở lên.
Git.
uv để quản lý dependency và môi trường.
Đủ dung lượng ổ đĩa cho mô hình và runtime đã chọn.

Bản tải xuống mô hình Spark-X2.5-4B Q8_0 mặc định có dung lượng khoảng 4.4 GB. Dung lượng tải xuống runtime thay đổi tùy nền tảng, từ khoảng 11 MB trên máy Mac đến khoảng 570 MB đối với gói CUDA.

Cài đặt và khởi động máy chủ

Clone repository, đồng bộ các dependency đã ghim, tải runtime và mô hình mặc định, rồi khởi động dịch vụ:

git clone https://github.com/Rizzo-AI-Academy/rizzo-flow
cd rizzo-flow
uv sync --locked
uv run rizzo download
uv run rizzo serve

Lệnh tải xuống sẽ chọn gói llama.cpp dựng sẵn chính thức cho máy hiện tại, xác minh checksum SHA-256 và tải Spark-X2.5-4B Q8_0. Các lượt tải bị gián đoạn có thể tiếp tục từ nơi đã dừng.

Theo tài liệu dự án, quá trình tải mô hình mất khoảng mười giây. Khi dịch vụ sẵn sàng, hãy mở:

http://127.0.0.1:8017/playground để mở playground trực quan.
http://127.0.0.1:8017/docs để mở tài liệu OpenAPI tương tác.
http://127.0.0.1:8017/snake để mở bản minh họa Snake.

Playground quyết định cục bộ của Rizzo Flow

Playground bao gồm các ví dụ có sẵn, công cụ tạo câu hỏi, trình chỉnh sửa JSON thô cho cả hai API, thanh xác suất, thông tin chi tiết về thời gian và các lệnh cURL tương đương. Playground không thực hiện cuộc gọi bên ngoài và có thể chuyển đổi giữa tiếng Anh và tiếng Ý.

Sử dụng mô hình nhỏ hơn

Để tải xuống lần đầu nhanh hơn, hãy cài đặt mô hình 1.7B:

uv run rizzo download --size 1.7b
uv run rizzo serve --size 1.7b

Tệp 1.7B Q8_0 có dung lượng khoảng 1.8 GB và chạy nhanh hơn khoảng hai lần, nhưng README cảnh báo rằng độ chính xác thấp hơn nhiều. Tệp này cũng có xu hướng chọn tùy chọn không đủ bằng chứng khi bật cơ chế từ chối trả lời, vì vậy hãy kiểm thử cẩn thận trên khối lượng công việc của riêng bạn.

Đưa ra quyết định đầu tiên

Bài kiểm thử API nhanh nhất sử dụng endpoint POST /v1/systemone tương thích với Jev. Yêu cầu sau đây hỏi liệu một tin nhắn hỗ trợ có thể hiện tính khẩn cấp hay không:

curl http://127.0.0.1:8017/v1/systemone \
  -H 'Content-Type: application/json' \
  -d '{
    "state": "Help! My payouts have been failing for 3 days.",
    "model": "rizzo-latest",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "Does this convey urgency?"
      }
    }
  }'

Kết quả noul là xác suất của câu trả lời có, được biểu diễn dưới dạng một số từ không đến một. Phản hồi báo cáo mã định danh thực tế của mô hình cục bộ, ngay cả khi yêu cầu sử dụng rizzo-latest hoặc một bí danh tiện lợi.

Đặt nhiều câu hỏi trong một yêu cầu

Rizzo Flow được thiết kế để đánh giá nhiều câu hỏi trên cùng một trạng thái. Kết hợp chúng trong một yêu cầu cho phép các câu hỏi dùng chung bộ nhớ đệm KV của trạng thái:

curl http://127.0.0.1:8017/v1/systemone \
  -H 'Content-Type: application/json' \
  -d '{
    "state": "Help! My payouts have been failing for 3 days.",
    "model": "rizzo-latest",
    "questions": {
      "is_urgent": {
        "type": "noul",
        "instructions": "Does this convey urgency?"
      },
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "billing": "Payments, invoicing, refunds",
          "technical": "Bugs and outages",
          "sales": null
        }
      },
      "frustration": {
        "type": "score",
        "instructions": "How frustrated is the customer?",
        "criteria": ["Calm", "Frustrated", "Very angry"]
      }
    }
  }'

Phản hồi chứa xác suất câu trả lời có cho noul, xác suất của tất cả tùy chọn trong câu hỏi lựa chọn và điểm số có trọng số xác suất kèm chú giải. Giá trị usage.output_tokens luôn bằng không.

Sử dụng API quyết định gốc

Endpoint gốc POST /v1/decisions cung cấp đầy đủ tính năng của Rizzo Flow, bao gồm các câu hỏi số và cơ chế từ chối trả lời. Bốn loại câu hỏi là:

boolean: trả về giá trị đúng kiểu và xác suất của true.
choice: trả về tùy chọn được chọn và phân phối đầy đủ của các tùy chọn.
score: trả về điểm số có trọng số xác suất và được chuẩn hóa trên các cấp độ theo thứ tự.
numeric: trả về giá trị ước tính, trung vị, độ phân tán và xác suất nằm dưới hoặc trên phạm vi.

Ước tính giá trị số từ các mốc

Một câu hỏi số xác định các mốc đại diện tăng dần. Ví dụ này yêu cầu mô hình đọc phần trăm mức lấp đầy được báo cáo:

curl http://127.0.0.1:8017/v1/decisions \
  -H 'Content-Type: application/json' \
  -d '{
    "state": {"measurement": 75, "unit": "percent"},
    "questions": {
      "fill": {
        "type": "numeric",
        "instructions": "Read the reported fill percentage.",
        "unit": "percent",
        "anchors": [
          {"value": 0, "description": "Empty"},
          {"value": 50, "description": "Half full"},
          {"value": 75, "description": "Three quarters full"},
          {"value": 100, "description": "Completely full"}
        ]
      }
    }
  }'

Các mốc là những giá trị đại diện, không phải các khoảng thống kê. Giá trị trung bình được báo cáo vẫn nằm giữa mốc thấp nhất và cao nhất, trong khi các phân vị mô tả phân phối xác suất rời rạc trên những mốc này.

Hiểu về cơ chế từ chối trả lời

Các câu hỏi gốc cho phép từ chối trả lời theo mặc định. Rizzo Flow bổ sung một tùy chọn nội bộ cho trường hợp không đủ bằng chứng, trong khi các câu hỏi số cũng bao gồm khả năng nằm dưới hoặc trên phạm vi. Tùy thuộc vào tùy chọn và chính sách được chọn, giá trị chính có thể là null và trạng thái có thể báo cáo insufficient_evidence, out_of_range hoặc uncertain.

Định dạng tương thích với Jev không sử dụng cơ chế từ chối trả lời. Kết quả có/không của nó được tính trên chính xác hai tùy chọn. Nếu sử dụng mô hình 1.7B nhỏ hơn thông qua API gốc, hãy cân nhắc đặt allow_abstain thành false như dự án khuyến nghị, đồng thời xác thực tác động trên dữ liệu của bạn.

Chạy quyết định không cần máy chủ

Đối với tập lệnh, kiểm thử hoặc đánh giá một lần, hãy truyền trực tiếp tệp yêu cầu cho CLI:

uv run rizzo decide examples/ticket.json

Bạn cũng có thể kích hoạt môi trường ảo và bỏ tiền tố uv run:

source .venv/bin/activate
rizzo decide examples/ticket.json

Trong PowerShell, hãy kích hoạt bằng:

.venv\Scripts\activate

Chọn mô hình, phương pháp lượng tử hóa và thiết bị

Cấu hình mặc định sử dụng Spark-X2.5-4B Q8_0. Các phương pháp lượng tử hóa khác được tài liệu hóa là Q4_K_M và BF16:

4B Q8_0: khoảng 4.4 GB và là cấu hình mặc định.
4B Q4_K_M: khoảng 2.6 GB.
4B BF16: khoảng 8.2 GB.
1.7B Q8_0: khoảng 1.8 GB.
1.7B Q4_K_M: khoảng 1.1 GB.
1.7B BF16: khoảng 3.4 GB.

Kiểm tra các thiết bị mà môi trường chạy có thể nhận diện trước khi khởi động máy chủ:

uv run rizzo devices

Sau đó, bạn có thể chọn rõ ràng một họ thiết bị:

uv run rizzo serve --device cuda
uv run rizzo serve --device vulkan
uv run rizzo serve --device metal
uv run rizzo serve --device cpu

Các họ thiết bị được chỉ định là yêu cầu bắt buộc chứ không phải gợi ý, vì vậy Rizzo Flow không tự động hạ cấp một họ GPU cụ thể xuống CPU. Có thể tải riêng các gói runtime bổ sung:

uv run rizzo download --only runtime --runtime rocm
uv run rizzo download --only runtime --runtime sycl
uv run rizzo download --only runtime --runtime cpu

Cấu hình nâng cao và mẹo thực tế

Các câu hỏi liên quan theo lô

Đặt tất cả câu hỏi về cùng một trạng thái trong một yêu cầu. Đây là yếu tố cốt lõi trong thiết kế của Rizzo Flow: trạng thái được điền sẵn một lần, còn các hậu tố câu hỏi được đánh giá theo các lô siêu nhỏ. Kích thước lô siêu nhỏ mặc định của câu hỏi là bốn và có thể thay đổi bằng --batch-size.

uv run rizzo serve --batch-size 8

Lô lớn hơn không phải lúc nào cũng tốt hơn. Hãy so sánh độ trễ và mức tiêu thụ bộ nhớ trên máy đích.

Tăng ngữ cảnh một cách thận trọng

Mặc dù Spark-X2.5 có ngữ cảnh gốc lên tới một triệu token, máy chủ mặc định sử dụng 8,192 token cho mỗi câu hỏi. Tăng giới hạn bằng --ctx:

uv run rizzo serve --ctx 32768

Bộ nhớ đệm KV được cấp phát khi khởi động. Đối với mô hình 4B, README ước tính khoảng 144 KiB cho mỗi token, tương đương khoảng 1.4 GiB ở giới hạn mặc định và 4.8 GiB với 32,000 token. Các đầu vào vượt quá giới hạn đã cấu hình sẽ bị từ chối thay vì bị cắt ngắn. Khi vượt khoảng 60,000 token, cũng cần tăng giới hạn trạng thái 256 KB trong schema.py của kho mã.

Bảo mật các endpoint tương thích

Đặt RIZZO_API_KEY trước khi khởi động máy chủ để yêu cầu xác thực Bearer trên các endpoint tương thích với Jev:

export RIZZO_API_KEY="replace-with-a-secret"
uv run rizzo serve

Trên Windows PowerShell:

$env:RIZZO_API_KEY = "replace-with-a-secret"
uv run rizzo serve

Lỗi xác thực trả về HTTP 401. Dữ liệu yêu cầu không hợp lệ có thể trả về HTTP 422.

Chuyển hướng một client tương thích

Một client được thiết kế cho TypeSafe API được lưu trữ có thể trỏ đến dịch vụ cục bộ bằng cách thay đổi URL cơ sở:

export TYPESAFE_BASE_URL=http://127.0.0.1:8017

Dự án cho biết thiết lập biến môi trường này được thiết kế cho các SDK chính thức, nhưng chưa được kiểm thử với chúng. Giao diện tương thích, nhưng mô hình cục bộ bên dưới không phải Jev.

Hiểu đúng độ tin cậy và xác suất

Giá trị độ tin cậy của API tương thích mô tả hình dạng của phân phối các tùy chọn. Đây không phải là xác suất đã được xác minh rằng câu trả lời là chính xác. Tương tự, xác suất thô của mô hình có thể quá tự tin hoặc chưa được hiệu chỉnh phù hợp.

Hãy xác thực các quyết định trên một tập dữ liệu đã gắn nhãn mang tính đại diện và hiệu chỉnh chúng cho môi trường triển khai thực tế khi cần. Máy chủ chấp nhận tệp hiệu chỉnh thông qua --calibration:

uv run rizzo serve --calibration fit.json

Một bộ hiệu chỉnh gắn với tệp mô hình, runtime, lượng tử hóa và backend phần cứng nơi nó được xây dựng. CUDA, Vulkan và Metal có thể làm tròn khác nhau, còn lượng tử hóa có thể thay đổi các xác suất được trả về.

Tôn trọng giới hạn ô trả lời

Mỗi ứng viên tương ứng với một chữ cái viết hoa, tạo ra tối đa 26 ô trả lời cho mỗi câu hỏi. Các tùy chọn từ chối trả lời nội bộ và tùy chọn phạm vi cũng sử dụng các ô. Do đó, một câu hỏi lựa chọn hỗ trợ tối đa 26 tùy chọn thông thường nếu không có tùy chọn từ chối, hoặc 25 tùy chọn khi có tùy chọn từ chối. Câu hỏi dạng số có ít mốc khả dụng hơn vì các lựa chọn dưới phạm vi, trên phạm vi và không đủ bằng chứng (nếu có) cũng chiếm các ô.

Sử dụng tệp mô hình hoặc bản dựng llama.cpp tùy chỉnh

Khởi động máy chủ với một tệp GGUF cụ thể bằng --model:

uv run rizzo serve --model /path/to/model.gguf

Để sử dụng bản cài đặt llama.cpp tùy chỉnh, trỏ RIZZO_LLAMA_DIR đến thư mục chứa libllama. README yêu cầu commit llama.cpp 161755f vì các binding gắn với header của phiên bản đó.

Khám phá bản trình diễn Snake

Rizzo Flow đưa ra quyết định di chuyển Snake theo thời gian thực

Trang Snake cục bộ minh họa cách các quyết định dạng văn bản có thể điều khiển một ứng dụng tương tác. Mỗi nước đi gửi một yêu cầu POST /v1/decisions chứa mô tả bàn chơi và một câu hỏi lựa chọn liệt kê các nước đi hợp lệ. Trang hiển thị xác suất câu trả lời, logit, thời gian xử lý và nhật ký quyết định mà không tạo văn bản.

Bản trình diễn cũng cho thấy một bài học quan trọng về mô hình hóa: cách biểu diễn đầu vào rất quan trọng. README cho biết mô hình 4B hoạt động tốt hơn nhiều với các cảm biến được tính toán cho từng nước đi so với chỉ sử dụng lưới ASCII. Những quan sát này đến từ một số ít ván chơi không chính thức và không nên được xem là điểm chuẩn.

Kiểm tra vận hành

Sử dụng GET /health để kiểm tra nguồn gốc mô hình và các mã băm tệp. Lược đồ yêu cầu và phản hồi cũng có trong request.schema.json và response.schema.json. Để triển khai có thể tái lập, hãy cố định mô hình, lượng tử hóa, runtime, backend, cấu hình ngữ cảnh và bộ hiệu chỉnh.

README báo cáo khoảng 50 mili giây cho một quyết định ngắn với Spark-X2.5-4B Q8_0 trên RTX 5060 Ti, nhưng con số này phụ thuộc vào phần cứng và khối lượng công việc. Tài liệu tương tự cũng lưu ý rằng các cấu hình Apple Silicon, AMD, Intel, Linux NVIDIA và CPU chưa được kiểm thử tương đương, vì vậy hãy đo kiểm trên máy của bạn trước khi đặt kỳ vọng về độ trễ.

Kết luận

Rizzo Flow cung cấp một giao diện cục bộ thiết thực để chuyển đổi trạng thái không có cấu trúc thành các quyết định xác suất có kiểu mà không tạo văn bản. Hãy bắt đầu với playground, kết hợp các câu hỏi liên quan vào một yêu cầu và sử dụng API gốc khi cần các ước tính số hoặc cơ chế từ chối dự đoán. Trước khi sử dụng trong môi trường production, hãy kiểm tra độ chính xác, độ trễ, hiệu chuẩn, lượng tử hóa và hành vi của backend trên dữ liệu phản ánh ứng dụng thực tế của bạn.