Chuyển đến nội dung chính
Hướng dẫn AI

Xây dựng API quyết định dựa trên suy luận với Jeeves

Tìm hiểu cách cài đặt Jeeves, cung cấp các trọng số đã phát hành, gửi yêu cầu quyết định tương thích với Jev và tích hợp SDK Python. Hướng dẫn này cũng giải thích các tùy chọn suy luận, sự đánh đổi về độ trễ, trình tạo nháp khuếch tán cùng quy trình đào tạo SFT và CISPO của dự án.

Thời gian đọc khoảng 23 phút
Xây dựng API quyết định dựa trên suy luận với Jeeves

Jeeves là gì?

Linh vật của dự án Jeeves

Jeeves là một trình phân loại kiểu Jev, tạo ra một chuỗi suy luận trước khi đưa ra quyết định có cấu trúc. Nó được xây dựng từ Qwen3.5-9B với các bộ điều hợp LoRA, một pointer head, xác suất được hiệu chỉnh và một diffusion drafter block-4. Kho lưu trữ bao gồm mã mô hình và drafter, pipeline huấn luyện, các công cụ đánh giá cùng dữ liệu huấn luyện, phát triển và kiểm thử.

Dự án được thiết kế cho các ứng dụng cần nhiều hơn việc sinh văn bản tự do. Với một trạng thái dùng chung và một hoặc nhiều câu hỏi, Jeeves trả về các câu trả lời có cấu trúc cùng xác suất thông qua API tương thích với Jev. Nhiều câu hỏi có thể được xử lý trong cùng một yêu cầu.

Tính năng chính

  • Ba loại quyết định: câu hỏi nhị phân noul, câu hỏi phân loại choice và câu hỏi thứ bậc score.
  • Suy luận trước khi quyết định: mô hình có thể tạo chuỗi suy luận, sau đó dùng pointer head để chấm điểm các lựa chọn có sẵn.
  • Đầu ra được hiệu chỉnh: xác suất cuối cùng của các lựa chọn sử dụng nhiệt độ được điều chỉnh trên tập phát triển.
  • API tương thích với Jev: các client Jev hiện có có thể gửi định dạng yêu cầu cốt lõi, trong khi các tùy chọn riêng của Jeeves kiểm soát việc suy luận.
  • SDK Python: gói sdk/ đi kèm là bản thay thế trực tiếp cho typesafe-sdk của Jev.
  • Soạn thảo bằng diffusion: drafter block-4 tăng tốc việc tạo chuỗi suy luận và hỗ trợ các lớp Gated DeltaNet của Qwen3.5.
  • Mã huấn luyện: kho lưu trữ chứa các thành phần SFT, CISPO, hiệu chỉnh, đánh giá, xuất mô hình và huấn luyện drafter.

Với suy luận tham lam được giới hạn ở 2.560 token, README báo cáo độ chính xác 0.889 trên tập kiểm thử giữ lại và ngoài miền, cùng 0.935 trên 231 mục JevBench công khai. Tuy nhiên, kết quả về kiến thức của mô hình thấp hơn Jev trên MMLU và MMLU-Pro, vì vậy mức độ phù hợp với benchmark phụ thuộc vào tác vụ.

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

Bạn cần Python 3.12 và GPU CUDA. Kernel FP8 của phần triển khai suy luận yêu cầu GPU Hopper. Chạy các lệnh sau từ thư mục gốc của kho lưu trữ.

Cài đặt các phần phụ thuộc

pip install -r requirements.txt

Tải xuống trọng số đã phát hành

Sử dụng CLI Hugging Face để tải checkpoint 9B đã công bố và drafter block-4 tương ứng:

hf download PostHog/jeeves --local-dir jeeves-weights

Mô hình đã phát hành có sẵn trên Hugging Face.

Khởi động máy chủ API

python -m inference.serve --model jeeves-weights --drafter jeeves-weights/drafter_k4.safetensors --port 8009

Lệnh này khởi động dịch vụ tương thích với Jev trên cổng 8009. Client Python đi kèm mặc định sử dụng http://127.0.0.1:8009, không yêu cầu khóa API và chờ phản hồi tối đa 120 giây.

Gửi yêu cầu quyết định đầu tiên

Endpoint /v1/systemone chấp nhận một state, một map questions và các tùy chọn suy luận không bắt buộc. Yêu cầu sau đề nghị Jeeves định tuyến vấn đề của khách hàng, quyết định xem có cần chuyển cấp hay không và đánh giá mức độ bức xúc của khách hàng.

curl -s localhost:8009/v1/systemone \
  -H 'content-type: application/json' \
  -d '{
    "state": "Giày đến muộn hai tuần và không đúng kích cỡ. Ngoài ra, tôi thấy thẻ của mình bị tính phí hai lần.",
    "questions": {
      "department": {
        "type": "choice",
        "instructions": "Đội ngũ nào nên xử lý việc này?",
        "criteria": {
          "returns": "Đổi hàng, hoàn tiền, sản phẩm sai hoặc bị hỏng",
          "shipping": "Tình trạng giao hàng, giao chậm, thất lạc kiện hàng",
          "billing": "Khoản phí, hóa đơn, vấn đề thanh toán"
        }
      },
      "escalate": {
        "type": "noul",
        "instructions": "Việc này có cần nhân viên xử lý khẩn cấp không?"
      },
      "frustration": {
        "type": "score",
        "instructions": "Khách hàng đang bức xúc đến mức nào?",
        "criteria": ["Bình tĩnh", "Bức xúc", "Rất tức giận"]
      }
    },
    "options": {"max_think": 512}
  }'

Tìm hiểu các loại câu hỏi

  • choice: chọn từ các phương án có tên và trả về khóa được chọn, xác suất cùng độ tin cậy.
  • noul: biểu diễn quyết định dạng có/không và trả về giá trị noul dạng số.
  • score: đánh giá một danh sách nhãn có thứ tự và trả về điểm số dạng số, chú giải, xác suất cùng độ tin cậy.

Phản hồi cũng chứa thông tin sử dụng, bao gồm số token đầu vào, đầu ra và suy luận, cùng tổng độ trễ. Các câu hỏi trong cùng một yêu cầu có thể được suy luận song song.

Sử dụng Jeeves từ Python

Cài đặt SDK đi kèm

pip install ./sdk

Tạo các câu hỏi có kiểu

from jeeves_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    result = client.system_one(
        state="I was charged twice. Please help.",
        questions={
            "billing": Noul(
                instructions="Is this about billing?"
            ),
            "tone": Choice(
                instructions="What is the tone?",
                criteria={"calm": None, "angry": None},
            ),
            "urgency": Score(
                instructions="How urgent is this?",
                criteria=["can wait", "this week", "today"],
            ),
        },
        max_think=768,
        return_reasoning=True,
    )

    print(result.nouls["billing"].noul)
    print(result.choices["tone"].choice)
    print(result.scores["urgency"].score)
    print(result.reasoning["tone"].text)

TypeSafeClient nhóm các giá trị trả về theo loại câu hỏi. Việc đặt return_reasoning=True cũng giúp cung cấp văn bản giải thích cho từng câu hỏi. README lưu ý rằng trong quá trình huấn luyện không sử dụng phần thưởng nhất quán ngôn ngữ, vì vậy các chuỗi giải thích không nhất thiết dễ diễn giải.

Kết nối với máy chủ khác

Theo mặc định, client hướng đến http://127.0.0.1:8009. Đặt biến môi trường JEEVES_BASE_URL khi máy chủ chạy tại địa chỉ khác.

export JEEVES_BASE_URL=http://your-server:8009

Kiểm soát quá trình suy luận và độ trễ

Đối tượng options tùy chọn cung cấp bốn tùy chọn kiểm soát suy luận. Các cờ tương ứng trên máy chủ có thể thiết lập giá trị mặc định trên toàn máy chủ.

  • think: mặc định là true. Đặt thành false để trả lời trực tiếp từ prompt mà không tạo chuỗi suy luận.
  • max_think: mặc định là 2560. Tham số này cắt ngắn mỗi chuỗi suy luận ở số token được chỉ định trước khi mô hình trả lời.
  • nothink_threshold: mặc định là null. Khi được cấu hình, Jeeves bỏ qua suy luận nếu độ tin cậy không suy luận đạt hoặc vượt ngưỡng.
  • return_reasoning: mặc định là false. Bật tùy chọn này để đưa văn bản giải thích vào phản hồi.

Chọn cấu hình độ trễ

Trong đánh giá phát triển gồm 325 câu hỏi của README, suy luận đầy đủ đạt độ chính xác 0.825, với trung bình 1,138 token suy luận và độ trễ trung vị 3.3 giây. Sử dụng max_think bằng 768 cùng nothink_threshold bằng 0.9 cho độ chính xác 0.806, trung bình 344 token suy luận và độ trễ trung vị 2.0 giây. Tắt suy luận cho độ chính xác 0.775 với thời gian khoảng 0.3 giây.

Một cấu hình cân bằng thực tế là:

{
  "options": {
    "max_think": 768,
    "nothink_threshold": 0.9,
    "return_reasoning": false
  }
}

Suy luận đầy đủ có phần đuôi độ trễ dài: p90 được báo cáo là 17.1 giây. Hãy sử dụng chuỗi ngắn hơn hoặc suy luận dựa trên độ tin cậy khi thời gian phản hồi là yếu tố quan trọng.

Cách Jeeves đưa ra quyết định

Jeeves định dạng trạng thái, hướng dẫn câu hỏi và các tùy chọn trả lời bằng những token hiếm trong tokenizer Qwen. Sau đó, hệ thống tạo một chuỗi suy luận bắt đầu bằng dấu hiệu suy nghĩ. Sau quá trình suy luận, câu hỏi và các tùy chọn được lặp lại trước dấu hiệu quyết định.

Một đầu con trỏ tính tích vô hướng được chuẩn hóa giữa phép chiếu truy vấn tại dấu hiệu quyết định và các phép chiếu khóa tại ranh giới của từng tùy chọn. Softmax chuyển các điểm số đó thành xác suất, còn một nhiệt độ được khớp trên tập phát triển sẽ hiệu chỉnh chúng. Theo các thử nghiệm loại bỏ trong README, việc thay thế các token prompt đặc biệt bằng nhãn thông thường hoặc bỏ qua câu hỏi được lặp lại sau suy luận đều làm giảm hiệu năng.

Bộ soạn thảo diffusion

Bộ soạn thảo tùy chọn tăng tốc quá trình tạo suy luận thông qua giải mã suy đoán. Thành phần này điều chỉnh phương pháp diffusion Orthrus cho các lớp Gated DeltaNet của Qwen3.5 bằng cách cho phép các token mask thực hiện attention chéo đến các khóa và giá trị sau tích chập.

Thông lượng được báo cáo cho một câu hỏi tăng từ 109 token chuỗi mỗi giây với giải mã tham lam dạng đồ thị thuần túy lên 176 token mỗi giây với block 4. Block 8 đạt 193 token mỗi giây, nhưng block 4 vẫn là mặc định vì có chi phí thấp khi xử lý theo lô nhiều câu hỏi. Tám câu hỏi được xử lý theo lô với block 4 đạt tổng cộng khoảng 960 token chuỗi mỗi giây.

Phục vụ một checkpoint do bạn huấn luyện

Jeeves sử dụng LoRA trong quá trình huấn luyện. Trước khi phục vụ một checkpoint đã huấn luyện, hãy hợp nhất nó thành một mô hình độc lập và cung cấp tệp bộ soạn thảo tương ứng:

python export.py runs/cispo/final --out runs/fused
python -m inference.serve \
  --model runs/fused \
  --drafter runs/drafter_k4/drafter.safetensors \
  --port 8009

Tái tạo pipeline huấn luyện

Chuẩn bị các tập dữ liệu

Các script chuẩn bị tải những tập dữ liệu công khai từ Hugging Face tại các revision được ghim trong prep/public.py. Mỗi tập dữ liệu nguồn vẫn tuân theo giấy phép riêng.

python -m prep.prep

Chạy huấn luyện và đánh giá

Pipeline tái tạo được lập tài liệu sử dụng tám GPU. Pipeline này thực hiện tinh chỉnh có giám sát, huấn luyện CISPO, đánh giá trên test và JevBench, xuất mô hình, tạo chuỗi và huấn luyện bộ soạn thảo block-4.

torchrun --nproc_per_node 8 train.py sft --run-dir runs/sft

torchrun --nproc_per_node 8 train.py cispo \
  --run-dir runs/cispo \
  --init runs/sft/final

torchrun --nproc_per_node 8 test.py runs/cispo/final
torchrun --nproc_per_node 8 jevbench.py runs/cispo/final
python export.py runs/cispo/final --out runs/fused

torchrun --nproc_per_node 8 -m drafter.gen --model runs/fused

torchrun --nproc_per_node 8 train.py drafter \
  --model runs/fused \
  --block 4 \
  --run-dir runs/drafter_k4

Công thức đã công bố trước tiên chạy hai epoch SFT trên 19.126 câu hỏi từ 12 bộ dữ liệu công khai và dữ liệu chính sách tổng hợp. Sau đó, công thức áp dụng CISPO với tám lượt suy luận cho mỗi câu hỏi, nhiệt độ 1 và giới hạn suy luận 2.560 token. Quá trình huấn luyện dừng ở bước 402 trong tổng số 624 bước dự kiến vì các bước sau khiến đầu con trỏ trở nên quá nhạy trên tập học tăng cường đã bão hòa. Cuối cùng, một giá trị nhiệt độ hiệu chuẩn được khớp trên tập phát triển.

Mẹo sử dụng nâng cao

  1. Gộp các quyết định liên quan theo lô. Đặt nhiều câu hỏi trong một trạng thái dùng chung để máy chủ có thể xử lý song song các chuỗi suy luận của chúng.
  2. Dùng câu trả lời trực tiếp cho các trường hợp dễ. Cấu hình nothink_threshold để dành suy luận cho những quyết định có độ tin cậy khi không suy nghĩ thấp hơn ngưỡng bạn chọn.
  3. Giới hạn suy luận trong các dịch vụ nhạy với độ trễ. Giảm max_think thay vì tắt hoàn toàn suy luận khi bạn muốn đạt sự cân bằng giữa tốc độ và độ chính xác.
  4. Chỉ trả về suy luận khi cần. Để return_reasoning ở trạng thái tắt trừ khi ứng dụng cần văn bản này, đặc biệt vì các chuỗi suy luận không đảm bảo dễ diễn giải ngay.
  5. Đánh giá trên miền riêng của bạn. Jeeves đạt kết quả tốt trên tập kiểm thử của dự án và các cấp JevBench công khai, nhưng kém Jev trong các đánh giá kiến thức MMLU và MMLU-Pro được báo cáo.
  6. Diễn giải các phép so sánh một cách thận trọng. Ngoài JevBench, các phép so sánh Kev và Jev được công bố sử dụng những mục khác nhau từ cùng các nguồn nền tảng.

Kết luận

Jeeves kết hợp các đầu ra có cấu trúc theo phong cách Jev với suy luận tại thời điểm kiểm thử, xác suất đã hiệu chuẩn và khả năng tạo chuỗi suy luận tăng tốc. Hãy bắt đầu với các trọng số được phát hành và endpoint HTTP tương thích với Jev, sử dụng SDK Python cho mã ứng dụng có kiểu dữ liệu, đồng thời tinh chỉnh max_think và nothink_threshold để cân bằng độ chính xác với độ trễ. Để tùy biến sâu hơn, kho mã cung cấp đầy đủ pipeline SFT, CISPO, hiệu chuẩn, xuất và drafter.