Xây dựng OpenAI-Compatible Inference Server trên GPU của riêng bạn: Hướng dẫn API tương thích OpenAI cho vLLM Inference Server

Nếu bạn đã có sẵn năng lực GPU, một inference server tương thích OpenAI sẽ cho phép ứng dụng của bạn giữ nguyên hình dạng client trong khi bạn chuyển backend từ API mô hình được lưu trữ sang hạ tầng của riêng mình. Con đường phổ biến khá đơn giản về mặt khái niệm: chạy vLLM hoặc LocalAI trên một node GPU, mở ra API /v1, trỏ base_url của SDK đến endpoint đó, rồi gia cố dịch vụ cho xác thực, định tuyến, giám sát và dung lượng.

Hướng dẫn này tập trung vào phần triển khai thực tế: cách dựng một vllm inference server openai compatible api, những gì cần kiểm thử trước khi đặt nó sau lưu lượng production, và khi nào sẽ thông minh hơn nếu coi self-hosting là một benchmark trong khi vẫn định tuyến phần lớn khối lượng công việc qua một API mô hình được quản lý như Flatkey.

Câu trả lời nhanh

Với hầu hết workload văn bản LLM, hãy bắt đầu với vLLM. Nó cung cấp một HTTP server tương thích OpenAI, hỗ trợ các endpoint kiểu OpenAI phổ biến như chat completions, completions, embeddings và liệt kê model tùy theo loại model được nạp, đồng thời đi kèm các image Docker chính thức để triển khai.

Một stack tự host tối thiểu trông như sau:

Hãy dùng một vllm inference server openai compatible api khi bạn cần kiểm soát phần cứng trực tiếp, tính gần dữ liệu, trọng số model tùy chỉnh, hoặc kinh tế phục vụ khối lượng lớn có thể dự đoán. Hãy dùng baseline gateway/model API khi bạn chủ yếu cần đầu ra đáng tin cậy và không muốn tự quản lý mức sử dụng GPU, sự lệch driver, việc nạp model và failover.

Trước Khi Xây: Quyết Định Xem Self-Hosting Có Đáng Không

Vận hành inference server tương thích OpenAI của riêng bạn không tự động rẻ hơn. Nó có thể rất tốt khi GPU của bạn luôn bận và workload của bạn phù hợp với model bạn host. Nó có thể tốn kém khi mức sử dụng thất thường, prompt thay đổi mạnh, chất lượng model thay đổi thường xuyên, hoặc đội ngũ dành nhiều thời gian debug hạ tầng hơn là ship sản phẩm.

Hãy dùng bảng quyết định này trước khi thuê hoặc mua phần cứng:

Flatkey phù hợp với cột cuối như một baseline: một endpoint tương thích OpenAI, một hóa đơn, và quyền truy cập vào nhiều model chính thức. Ngay cả khi bạn xây một vllm inference server openai compatible api, hãy giữ một baseline API mô hình trong benchmark của bạn để bạn có thể so sánh độ trễ, chất lượng và chi phí trên mỗi đầu ra được chấp nhận, thay vì chỉ chi phí trên mỗi giờ GPU.

Kiến trúc tham chiếu

Một inference server production tương thích OpenAI không nên mở trực tiếp engine model ra internet công cộng. Hãy đặt một lớp điều khiển mỏng ở phía trước nó.

flowchart LR
  A[OpenAI SDK / app workers] --> B[API edge: TLS, auth, rate limits]
  B --> C[OpenAI-compatible /v1 route]
  C --> D[vLLM inference server]
  D --> E[GPU node or GPU pool]
  D --> F[Metrics and logs]
  B --> G[Fallback route: Flatkey or another model API]

Quyết định thiết kế quan trọng là tách biệt khả năng tương thích khỏi vận hành. vLLM có thể nói API theo kiểu OpenAI. Edge của bạn nên chịu trách nhiệm về xác thực, quota, giới hạn kích thước request, TLS, audit logs và hành vi fallback.

Bước 1: Chuẩn bị GPU Host

Bắt đầu với một máy Linux GPU sạch. Xác nhận host có:

• Driver NVIDIA tương thích với GPU và stack CUDA mà bạn dự định chạy.
• Docker hoặc một container runtime được hỗ trợ khác.
• NVIDIA Container Toolkit được cấu hình để container có thể truy cập GPU.
• Đủ bộ nhớ lưu trữ cục bộ hoặc mạng cho trọng số model.
• Một đường mạng không phơi bày inference port cho đến khi đã có xác thực và TLS.

Bộ công cụ container của NVIDIA cấu hình Docker bằng nvidia-ctk runtime configure --runtime=docker, sau đó khởi động lại Docker. Sau đó, có thể chạy container với quyền truy cập GPU bằng các cờ GPU của Docker.

Chạy các kiểm tra sau trước khi cài đặt model server:

nvidia-smi
docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi

Nếu một trong hai lệnh thất bại, hãy sửa lớp driver/runtime trước. Một vllm inference server openai compatible api không thể ổn định khi runtime GPU nền tảng không ổn định.

Bước 2: Khởi động một vLLM Inference Server OpenAI Compatible API

Tài liệu triển khai Docker chính thức của vLLM xác định vllm/vllm-openai là image để chạy một server tương thích OpenAI. Một lần chạy ban đầu thực tế sẽ như sau:

docker run --rm --gpus all \
  --ipc=host \
  -p 8000:8000 \
  -e HUGGING_FACE_HUB_TOKEN="$HUGGING_FACE_HUB_TOKEN" \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --served-model-name llama-3.1-8b-instruct

Đối với model riêng tư, hãy thay model id bằng repository của bạn hoặc đường dẫn cục bộ. Trong production, hãy ghim tag image và các revision của model thay vì triển khai latest.

Sau đó kiểm tra danh sách model:

curl http://localhost:8000/v1/models

Và kiểm tra chat completions:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b-instruct",
    "messages": [
      {"role": "system", "content": "Bạn là một trợ lý ngắn gọn."},
      {"role": "user", "content": "Trả lời một câu về inference tự host."}
    ],
    "temperature": 0.2
  }'

Đó là mốc đầu tiên hoạt động: một vllm inference server openai compatible api cục bộ mà ứng dụng của bạn có thể gọi bằng cùng cấu trúc request mà nó đã dùng cho chat kiểu OpenAI.

Bước 3: Trỏ SDK hiện có của bạn tới endpoint cục bộ

Phần lớn công việc chuyển đổi tương thích OpenAI nên diễn ra trong cấu hình, không phải trong logic ứng dụng. Với mẫu SDK Python, hãy đặt base_url và API key tùy chỉnh:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="local-dev-key",
)

response = client.chat.completions.create(
    model="llama-3.1-8b-instruct",
    messages=[
        {"role": "user", "content": "Hãy cho tôi một checklist triển khai."}
    ],
)

print(response.choices[0].message.content)

Trong production, đừng trỏ trực tiếp worker của ứng dụng tới một tiến trình vLLM thô. Hãy trỏ chúng tới gateway nội bộ hoặc load balancer của bạn:

OPENAI_BASE_URL=https://inference.example.com/v1
OPENAI_API_KEY=<your-internal-service-token>

Gateway đó có thể định tuyến tới vLLM, chặn các trường request không được hỗ trợ, chuẩn hóa các bí danh model, và chuyển sang Flatkey hoặc một API model khác khi cụm tự host bị quá tải.

Bước 4: Hiểu rõ "OpenAI-Compatible" không có nghĩa là gì

OpenAI-compatible không có nghĩa là mọi endpoint, hành vi của model, lời gọi tool, sự kiện streaming hay tùy chọn đặc thù của nhà cung cấp đều hoạt động y hệt OpenAI. Nó có nghĩa là server chấp nhận một cấu trúc quen thuộc cho các endpoint được chọn.

Trước khi coi việc migration là hoàn tất, hãy kiểm tra:

Mẫu an toàn nhất là duy trì một bộ kiểm thử tương thích. Gửi một bộ cố định các prompt ứng dụng thực tế tới OpenAI, Flatkey và vllm inference server openai compatible api của bạn. So sánh độ trễ, tính hợp lệ của schema, hành vi từ chối, chất lượng đầu ra và tỷ lệ đầu ra được chấp nhận.

Bước 5: Tính toán bộ nhớ GPU cho model và lưu lượng

Chế độ lỗi chính khi phục vụ không phải là "server khởi động chậm." Mà là "server khởi động được, rồi sập khi gặp độ dài context thực tế và mức đồng thời cao."

Lên kế hoạch bộ nhớ dựa trên:

• Trọng số model.
• KV cache cho context và các chuỗi đồng thời.
• Overhead của runtime.
• Phân mảnh và khoảng dự phòng.
• Tensor parallelism khi một model không vừa trên một GPU.
• Đánh đổi quantization nếu bạn dùng độ chính xác thấp hơn.

Để có một worksheet chuyên sâu hơn, hãy dùng hướng dẫn Flatkey về yêu cầu bộ nhớ GPU cho LLM. Ở cấp độ lập kế hoạch cụm, hãy kết hợp điều này với phân tích kiểu kiến trúc cụm GPU và TCO của cụm GPU.

Một quy tắc chấp nhận sơ bộ:

usable_capacity = model_fit + target_context + target_concurrency + 20-30% headroom

Nếu bạn không thể giữ được phần headroom này, hãy giảm độ dài ngữ cảnh, giảm mức đồng thời, dùng mô hình nhỏ hơn, chia trên nhiều GPU, hoặc chuyển lưu lượng vượt quá sang khỏi cụm tự vận hành.

Bước 6: Thêm một API Edge trước khi lên production

Máy chủ vLLM thô không phải toàn bộ control plane production của bạn. Hãy đặt một lớp edge phía trước nó và giao cho lớp edge chịu trách nhiệm về:

• Kết thúc TLS.
• Xác thực service-to-service.
• Giới hạn kích thước body yêu cầu.
• Rate limit theo từng team hoặc từng ứng dụng.
• Ánh xạ bí danh mô hình.
• Nhật ký yêu cầu có cấu trúc.
• Ngân sách timeout và retry.
• Định tuyến canary.
• Định tuyến dự phòng.

Ví dụ cấu trúc Nginx:

server {
  listen 443 ssl;
  server_name inference.example.com;

  client_max_body_size 4m;

  location /v1/ {
    proxy_pass http://vllm_backend:8000/v1/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Request-Id $request_id;
    proxy_read_timeout 120s;
  }
}

Đó chỉ là điểm khởi đầu. Các đội production nên bổ sung xác thực, mTLS hoặc mạng riêng, chính sách ghi log yêu cầu, và các giới hạn rõ ràng về kích thước prompt và độ dài đầu ra.

Bước 7: Đo đầu ra được chấp nhận, không chỉ tokens mỗi giây

Các dashboard phục vụ GPU thường quá tập trung vào thông lượng. Tokens mỗi giây là quan trọng, nhưng các đội sản phẩm thường quan tâm đến đầu ra được chấp nhận: phản hồi đủ nhanh, đủ hợp lệ và đủ tốt để giao cho người dùng hoặc quy trình downstream.

Theo dõi:

Sau đó tính chi phí trên mỗi đầu ra được chấp nhận:

cost_per_accepted_output =
  (gpu_cost + storage + network + ops_time + fallback_api_cost)
  / accepted_outputs

Đây là lúc một vllm inference server openai compatible api được so sánh một cách trung thực với các API được quản lý. Nếu GPU cục bộ rẻ hơn trên mỗi token thô nhưng tệ hơn về số lần retry, lỗi, hoặc thời gian của người vận hành, thì chi phí trên mỗi đầu ra được chấp nhận có thể cao hơn kỳ vọng.

Bước 8: Thêm cơ chế fallback thay vì coi hộp GPU là một điểm lỗi đơn lẻ

Ứng dụng của bạn không nên quan tâm phản hồi đến từ vLLM tự vận hành, Flatkey hay một tuyến mô hình khác. Nó nên yêu cầu một model alias và nhận về phản hồi hoặc một lỗi được kiểm soát.

Sử dụng các quy tắc định tuyến như:

Thiết kế này giúp đội ngũ giữ được kinh tế và quyền kiểm soát của self-hosting mà không buộc tính sẵn sàng của sản phẩm phụ thuộc vào một inference server.

vLLM vs LocalAI cho suy luận cục bộ tương thích OpenAI

vLLM và LocalAI đều xuất hiện trong các tìm kiếm về một inference server tương thích OpenAI, nhưng chúng phù hợp với các công việc khác nhau.

Với workload mục tiêu của bài viết này, hãy bắt đầu bằng một vllm inference server openai compatible api. Hãy đánh giá LocalAI khi mục tiêu của bạn là thử nghiệm cục bộ rộng hơn hoặc một API cục bộ duy nhất trên nhiều backend, thay vì thông lượng phục vụ GPU tối đa cho một họ LLM.

Danh sách kiểm tra Production

Hãy dùng danh sách này trước khi bạn định tuyến người dùng thực:

• [ ] Trình điều khiển GPU và container runtime đã được xác minh với nvidia-smi bên trong container.
• [ ] Đã ghim tag image vLLM và revision của model.
• [ ] Alias của model ổn định và được tài liệu hóa.
• [ ] /v1/models và /v1/chat/completions đã được kiểm thử thông qua URL edge cuối cùng.
• [ ] Đã kiểm thử streaming với các lần client ngắt kết nối.
• [ ] Đã chạy kiểm thử long-context và concurrency ở mức tải sản xuất dự kiến.
• [ ] Đã thêm xác thực ở lớp edge; cổng gốc của vLLM không được công khai.
• [ ] Đã áp dụng giới hạn kích thước request body, số lượng output token tối đa và timeout.
• [ ] Log không bao gồm dữ liệu prompt nhạy cảm trừ khi được phê duyệt rõ ràng.
• [ ] Metrics ghi nhận độ trễ, queueing, bộ nhớ GPU, tỷ lệ lỗi và tỷ lệ output được chấp nhận.
• [ ] Đã cấu hình route dự phòng cho tình trạng quá tải và sự cố.
• [ ] Đã đo baseline API được quản lý bằng cùng các prompt.
• [ ] Đã kiểm thử kế hoạch rollback.

Các Sai Lầm Thường Gặp

Sai lầm lớn nhất là coi lệnh curl thành công đầu tiên như điểm kết thúc của công việc. Nó chỉ là sự khởi đầu.

Các lỗi thường gặp khác:

• Chạy image latest trong production mà không ghim phiên bản.
• Phơi bày cổng inference gốc ra internet.
• Cho rằng mọi tham số request của OpenAI đều được hỗ trợ.
• Benchmark một prompt ngắn rồi gọi kết quả là "sẵn sàng cho production."
• Bỏ qua sự tăng trưởng của KV cache theo độ dài context thực tế.
• Quên rằng thời gian load model ảnh hưởng đến deploy và khôi phục.
• Đo chi phí GPU-hour mà không tính thời gian vận hành, retry và lỗi chất lượng.
• Bỏ qua fallback vì endpoint cục bộ là "OpenAI-compatible."

Một vllm inference server openai compatible api cho production là hạ tầng hữu ích. Nó không phải là khả năng tương thích kỳ diệu, và cũng không thay thế cho kỷ luật vận hành.

Khi Nào Nên Dùng Flatkey Cùng Với GPU Của Bạn

Flatkey hữu ích nhất trong kiến trúc này như baseline model/API được quản lý và đường fallback. Hãy giữ ứng dụng của bạn theo dạng client tương thích OpenAI, rồi định tuyến một phần traffic đến pool GPU cục bộ của bạn và một phần đến Flatkey.

Điều đó mang lại cho bạn:

• Một cách để so sánh chất lượng đầu ra của hệ thống tự vận hành với các model được host.
• Khả năng xử lý overflow khi GPU cục bộ bị quá tải.
• Một route dự phòng trong các sự cố về driver, model hoặc triển khai.
• Quyền truy cập vào các họ model khác mà không cần thêm nhiều provider key.
• Một đường quay lại các API được quản lý rõ ràng hơn nếu model tự host hoạt động kém.

Quyết định không phải là "tự sở hữu GPU hay dùng API." Với nhiều đội ngũ, thiết lập bền vững là cả hai: sở hữu đường GPU ở nơi nó mang lại quyền kiểm soát hoặc lợi thế chi phí, và giữ một route được quản lý để tăng độ bền và lựa chọn model.

FAQ

Inference server tương thích OpenAI là gì?

Một inference server tương thích OpenAI cung cấp các HTTP endpoint với dạng request và response theo kiểu OpenAI, thường nằm dưới /v1. Điều đó cho phép ứng dụng dùng cấu hình SDK quen thuộc như base_url tùy chỉnh trong khi gửi traffic đến backend khác.

vLLM có phải là một inference server tương thích OpenAI không?

Có. vLLM cung cấp server tương thích OpenAI và tài liệu hóa hỗ trợ cho các endpoint kiểu OpenAI phổ biến như chat completions, completions, embeddings và liệt kê model, tùy thuộc vào loại model và tính năng.

Tôi có thể chạy server vLLM tương thích OpenAI trên máy cục bộ không?

Có. Bạn có thể chạy vLLM cục bộ trên một máy trạm hoặc server GPU, sau đó công khai endpoint /v1 cho ứng dụng của bạn. Trong production, hãy đặt một lớp edge hoặc gateway nội bộ có xác thực ở phía trước nó.

Tôi cần phần cứng gì?

Điều đó phụ thuộc vào kích thước model, độ chính xác, độ dài context và mục tiêu concurrency. Hãy bắt đầu bằng việc tính toán dung lượng cho trọng số model cộng với KV cache và phần dự phòng, rồi kiểm thử với prompt thực tế. Một model instruct nhỏ có thể vừa trên một GPU; một model 70B hoặc workload có concurrency cao có thể cần GPU bộ nhớ lớn hơn hoặc tensor parallelism.

Tôi nên dùng vLLM hay LocalAI?

Hãy dùng vLLM trước khi tác vụ là inference LLM throughput cao trên GPU. Đánh giá LocalAI khi bạn muốn một server tương thích OpenAI cục bộ rộng hơn trên nhiều backend hoặc modality cục bộ khác nhau.

OpenAI-compatible có nghĩa là thay thế trực tiếp hoàn toàn giống hệt không?

Không. Dạng endpoint có thể khớp, nhưng hành vi model, tham số được hỗ trợ, tools, streaming, embeddings, lỗi và cách tính token có thể khác nhau. Hãy chạy kiểm thử tương thích trước khi chuyển traffic production.

Kết luận

Xây dựng một vllm inference server openai compatible api là cách thực tế nhanh nhất để biến GPU của riêng bạn thành một endpoint kiểu OpenAI. Phần xây dựng cốt lõi khá đơn giản: chuẩn bị GPU runtime, chạy vLLM, trỏ SDK đến /v1, rồi thêm edge, monitoring, kiểm thử tương thích và các route fallback để đưa nó lên mức production.

Các đội ngũ tốt nhất không dừng ở mức "nó chạy." Họ so sánh inference tự host với baseline API model được quản lý, đo accepted outputs và luôn giữ sẵn route fallback. Đó là cách bạn có được quyền kiểm soát từ GPU của riêng mình mà không làm cho mọi request của sản phẩm phụ thuộc vào một inference server mong manh.

Tài liệu Tham khảo Chính thức

• Tài liệu máy chủ tương thích với OpenAI của vLLM: https://docs.vllm.ai/en/latest/serving/online_serving/
• Tài liệu triển khai Docker của vLLM: https://docs.vllm.ai/en/latest/deployment/docker/
• Hướng dẫn cài đặt NVIDIA Container Toolkit: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
• README của OpenAI Python SDK: https://github.com/openai/openai-python
• Tài liệu dự án LocalAI: https://localai.io/