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

Chuyển đổi yêu cầu AI đa định dạng thành prompt DeepSeek V4.1 với deepseek-recipe

Tìm hiểu cách cài đặt và sử dụng deepseek-recipe bằng Python hoặc Rust, chuyển đổi yêu cầu Chat Completions thành các cuộc hội thoại, tạo prompt DeepSeek V4.1, đồng thời khám phá tính năng truyền dữ liệu trực tuyến, token hóa, tiền xử lý hình ảnh và phân tích cú pháp đầu ra.

Thời gian đọc khoảng 18 phút
Chuyển đổi yêu cầu AI đa định dạng thành prompt DeepSeek V4.1 với deepseek-recipe

deepseek-recipe là gì?

deepseek-recipe là một tập hợp các thư viện Rust và liên kết Python để kết nối các dịch vụ API với các backend suy luận DeepSeek. Thư viện chuyển đổi yêu cầu từ các định dạng API được hỗ trợ thành biểu diễn Conversation dùng chung, hiển thị các cuộc hội thoại đó dưới dạng prompt DeepSeek V4 hoặc V4.1, rồi chuyển đổi đầu ra của mô hình trở lại định dạng phản hồi tương ứng.

Dự án là một lớp xử lý giao thức và prompt, không phải một máy chủ suy luận hoàn chỉnh. Bạn phải cung cấp riêng phần suy luận mô hình, truyền tải HTTP và thực thi công cụ.

Quy trình xử lý hoạt động như thế nào

  1. Nhận yêu cầu ở định dạng Messages, Chat Completions hoặc Responses.
  2. Chuyển đổi yêu cầu sang định dạng Conversation chung của thư viện.
  3. Hiển thị cuộc hội thoại dưới dạng prompt DeepSeek V4 hoặc V4.1, hoặc mã hóa thành các ID token.
  4. Gửi prompt hoặc các ID token đến một backend suy luận bên ngoài.
  5. Phân tích đầu ra được tạo, bao gồm nội dung suy nghĩ được hỗ trợ, lệnh gọi công cụ, đối tượng JSON và chuỗi dừng.
  6. Trả về phản hồi hoàn chỉnh hoặc phản hồi dạng streaming theo định dạng mà client yêu cầu.

Bản thân deepseek-recipe không chạy mô hình, thực thi công cụ hoặc cung cấp dịch vụ HTTP. Kho lưu trữ có các máy chủ Rust và Python mẫu để tham khảo khi tích hợp.

Tính năng chính

  • Chuyển đổi giao thức hợp nhất: Xử lý các yêu cầu và phản hồi Messages, Chat Completions và Responses.
  • Mã hóa prompt DeepSeek: Hiển thị các cuộc hội thoại DeepSeek V4 và V4.1 dưới dạng prompt hoặc ID token.
  • Phản hồi streaming và hoàn chỉnh: Hỗ trợ chuyển đổi cả hai kiểu phản hồi.
  • Thiết lập sinh nội dung: Truyền chế độ suy nghĩ, mức độ suy luận, temperature, top_p và giới hạn token đầu ra.
  • Phân tích đầu ra: Nhận diện nội dung suy nghĩ, lệnh gọi công cụ từ client, đầu ra đối tượng JSON và chuỗi dừng.
  • Đầu vào đa phương thức: Chấp nhận hình ảnh được cung cấp dưới dạng dữ liệu base64 hoặc URL bên ngoài. Gói hình ảnh cung cấp tính năng tiền xử lý DeepSeek V4.1 với OpenCV.
  • Định nghĩa công cụ: Hỗ trợ các công cụ hàm. API Responses còn hỗ trợ không gian tên công cụ và công cụ tùy chỉnh apply_patch.

Cài đặt và thiết lập Python

Yêu cầu

Các liên kết Python yêu cầu Python 3.10 trở lên. Cài đặt gói đã phát hành bằng pip:

python3 -m pip install deepseek-recipe

Mô-đun sau khi cài đặt được import bằng tên deepseek_recipe.

Chuyển đổi yêu cầu Chat Completions

Ví dụ sau tạo một yêu cầu Chat Completions, chuyển đổi yêu cầu thành biểu diễn Conversation chung, rồi hiển thị cuộc hội thoại đó dưới dạng prompt DeepSeek V4.1:

from deepseek_recipe import (
    ChatCompletionRequest,
    ConversionOptions,
    DeepseekV41Encoding,
)

request = ChatCompletionRequest({
    "model": "deepseek-flash",
    "messages": [
        {"role": "user", "content": "Hello"}
    ],
})

converted = request.convert(ConversionOptions())
rendered = DeepseekV41Encoding().render_conversation(
    converted.conversation
)

print(rendered.prompt)

Tìm hiểu từng bước

  1. ChatCompletionRequest đọc dữ liệu Chat Completions đầu vào.
  2. request.convert(ConversionOptions()) chuẩn hóa yêu cầu thành một Conversation.
  3. DeepseekV41Encoding() chọn các quy tắc mã hóa DeepSeek V4.1.
  4. render_conversation tạo biểu diễn sẵn sàng cho mô hình.
  5. rendered.prompt chứa prompt để gửi đến backend suy luận bên ngoài của bạn.

Sau khi suy luận, hãy sử dụng các thành phần chuyển đổi phản hồi và phân tích đầu ra của dự án để chuyển đầu ra do mô hình tạo thành định dạng API mà client yêu cầu. Việc tích hợp cụ thể phụ thuộc vào việc backend của bạn trả về đầu ra hoàn chỉnh hay streaming dữ liệu được tạo.

Cài đặt và thiết lập Rust

Thêm các crate

Thêm các crate chuyển đổi giao thức và mã hóa vào một dự án Rust:

cargo add deepseek-recipe@0.1 deepseek-recipe-encoding@0.1

Nếu bạn xây dựng từ mã nguồn hoặc bật tính năng xử lý hình ảnh, hãy xem hướng dẫn phát triển trong kho lưu trữ để biết hướng dẫn xây dựng và các phụ thuộc hình ảnh.

Hiển thị prompt DeepSeek V4.1

use deepseek_recipe::openai::ChatCompletionRequest;
use deepseek_recipe::request::{ConversionOptions, ProtocolRequest};
use deepseek_recipe_encoding::PromptEncoding;
use deepseek_recipe_encoding::v4::dsv41::DeepseekV41Encoding;
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let request: ChatCompletionRequest = serde_json::from_value(json!({
        "model": "deepseek-flash",
        "messages": [
            {"role": "user", "content": "Hello"}
        ],
    }))?;

    let converted = request.convert(ConversionOptions::default())?;
    let rendered = DeepseekV41Encoding::new()
        .render_conversation(&converted.conversation);

    println!("{}", rendered.prompt);
    Ok(())
}

Ở đây, Serde giải tuần tự JSON thành ChatCompletionRequest. Trait ProtocolRequest cung cấp tính năng chuyển đổi yêu cầu, còn PromptEncoding cung cấp tính năng hiển thị cuộc hội thoại. Sau đó, prompt thu được có thể được truyền đến một công cụ suy luận được quản lý riêng.

Khám phá bản demo mã hóa và giải mã

Kho lưu trữ có một giao diện web để hiển thị prompt, kiểm tra các token đặc biệt và giải mã đầu ra hoàn chỉnh của mô hình thành các định dạng Chat Completions, Responses hoặc Messages.

Từ thư mục gốc của kho lưu trữ, chạy:

cargo run -p encoding-decoding-demo --locked

Sau đó mở http://127.0.0.1:7778 trong trình duyệt.

Bản demo này hữu ích để kiểm tra cấu trúc prompt và hiểu cách đầu ra được tạo ánh xạ trở lại các định dạng phản hồi API được hỗ trợ trước khi tích hợp các thư viện vào máy chủ.

Tổng quan về các gói

  • deepseek-recipe: Chuyển đổi giao thức và phân tích đầu ra của mô hình.
  • deepseek-recipe-core: Các kiểu dùng chung cho hội thoại, tin nhắn, hình ảnh và công cụ.
  • deepseek-recipe-encoding: Kết xuất prompt và mã hóa token cho DeepSeek V4 và V4.1.
  • deepseek-recipe-image: Tải và tiền xử lý hình ảnh.
  • deepseek-recipe-python: Các liên kết Python được cung cấp thông qua import deepseek_recipe.
  • encoding-decoding-demo: Kiểm tra prompt và đầu ra trên trình duyệt.
  • server-rs: Ví dụ API Axum sử dụng suy luận mô phỏng.
  • server-py: Ví dụ FastAPI sử dụng suy luận mô phỏng.

Mẹo tích hợp nâng cao

Tách riêng việc xử lý giao thức khỏi suy luận

Sử dụng deepseek-recipe tại các ranh giới của ứng dụng. Chuyển đổi request đầu vào trước khi suy luận và phân tích đầu ra được tạo sau đó. Giữ việc tải mô hình, xử lý theo lô, lập lịch và quản lý phần cứng bên trong backend suy luận.

Chủ động lựa chọn prompt hoặc ID token

Bạn có thể kết xuất hội thoại thành prompt dạng văn bản hoặc mã hóa chúng thành ID token. Sử dụng kết xuất prompt khi backend chấp nhận văn bản đã định dạng. Sử dụng mã hóa token khi backend hoạt động trực tiếp với ID của tokenizer. Hướng dẫn tokenizer của repository trình bày cách mã hóa hội thoại và giải mã ID token từ backend.

Lập kế hoạch streaming như một tính năng đầu-cuối

Cả Rust và Python đều hỗ trợ chuyển đổi đầu ra mô hình thành phản hồi streaming. Lớp truyền tải và backend suy luận của bạn cũng phải stream dữ liệu; thư viện không cung cấp các lớp đó. Hãy làm theo hướng dẫn phản hồi streaming khi kết nối đầu ra mô hình gia tăng với API hướng đến máy khách.

Xử lý hình ảnh trước khi suy luận

Request có thể tham chiếu hình ảnh thông qua nội dung base64 hoặc URL bên ngoài. Thành phần hình ảnh chuyên dụng hỗ trợ tải và tiền xử lý DeepSeek V4.1 bằng OpenCV. Đảm bảo đã cài đặt các phần phụ thuộc hình ảnh cần thiết khi build từ mã nguồn.

Để việc thực thi công cụ bên ngoài thư viện

Dự án có thể biểu diễn các định nghĩa công cụ và phân tích lệnh gọi công cụ từ máy khách, nhưng không thực thi các công cụ đó. Ứng dụng của bạn phải xác thực từng lệnh gọi, chạy hàm hoặc công cụ tùy chỉnh phù hợp, rồi thêm kết quả vào lượt hội thoại tiếp theo.

Tôn trọng các giới hạn hiện tại

Trước khi thiết kế API dựa trên dự án, hãy tính đến các tính năng chưa được hỗ trợ:

  • Xác suất token thông qua logprobs hoặc top_logprobs.
  • Nội dung tài liệu, đầu vào âm thanh hoặc video và việc truy xuất bằng file_id.
  • Các công cụ thực thi trên máy chủ như web_search.
  • Ràng buộc đầu ra bằng JSON Schema và biểu thức chính quy.
  • Thực thi các thiết lập strict của công cụ.
  • Nhiều lựa chọn Chat Completions khi n > 1.
  • Các định nghĩa công cụ tùy chỉnh của Responses ngoài apply_patch.
  • Lưu trữ hội thoại Responses hoặc truy xuất ngữ cảnh thông qua previous_response_id.
  • Nội dung suy nghĩ được mã hóa thông qua encrypted_content.

Kết luận

deepseek-recipe cung cấp các thành phần Rust và Python có thể tái sử dụng để chuẩn hóa nhiều giao thức API, tạo đầu vào DeepSeek V4 và V4.1, đồng thời chuyển đổi đầu ra được tạo trở lại thành phản hồi hướng đến máy khách. Hãy bắt đầu với ví dụ chuyển đổi request cơ bản, kiểm tra hành vi qua bản demo, sau đó kết nối pipeline chuyển đổi với hạ tầng suy luận, truyền tải và thực thi công cụ của riêng bạn.

Mã nguồn dự án và tài liệu công khai được cung cấp theo Giấy phép MIT.