Cấu hình API trung gian trong các khung phổ biến: từ SDK đến Dify

Chuẩn bị đủ ba giá trị

Dù dùng khung nào, bạn cũng cần xác nhận mình có đủ ba thứ này trước; các bước cấu hình tiếp theo chỉ là điền vào các trường.

• Địa chỉ endpoint: https://api.llmzhongzhuan.com/v1. Lưu ý giữ lại /v1 ở cuối nhưng đừng thêm /chat/completions, SDK sẽ tự ghép.
• Khóa API: Hiển thị ngay sau khi đăng ký bằng email và mật mã trên trang lấy khóa. Mỗi tài khoản chỉ có một khóa, có thể đặt lại; khóa cũ sẽ mất hiệu lực ngay lập tức.
• Tên mô hình: Chỉ có một, là uncensored. Bạn có thể tự xác nhận bằng cách gọi GET /v1/models.

Bạn cũng cần nhớ các giới hạn: tổng ngữ cảnh là 100,000 token, max_tokens mặc định là 2048 và tối đa 32,000, mỗi khóa giới hạn 300 yêu cầu mỗi phút. Các con số này sẽ xuất hiện lại trong phần cài đặt tham số.

Cách viết biến môi trường

Viết cứng khóa vào mã nguồn là nguyên nhân phổ biến gây sự cố. Cách tốt nhất là chỉ đọc biến môi trường và để hệ thống container hoặc quản lý khóa tiêm vào khi triển khai. Dưới đây dùng hai biến API_KEY và API_BASE, các ví dụ khung đều dùng hai tên này.

复制# Linux / macOS：写进 ~/.zshrc 或 .env 加载脚本
export API_KEY="替换为你的密钥"
export API_BASE="https://api.llmzhongzhuan.com/v1"

# Windows PowerShell（仅当前会话）
$env:API_KEY = "替换为你的密钥"
$env:API_BASE = "https://api.llmzhongzhuan.com/v1"

Nếu bạn dùng tệp .env, hãy nhớ thêm nó vào .gitignore. SDK Python chính thức mặc định đọc OPENAI_API_KEY và OPENAI_BASE_URL; bạn có thể giữ nguyên tên biến hoặc truyền rõ tham số trong hàm tạo như ví dụ dưới. Truyền rõ giúp tránh bị biến cũ còn sót trên máy làm nhiễu, giảm biến cần kiểm tra khi sửa lỗi.

SDK Python và SDK Node.js của OpenAI

Python cần gói openai phiên bản v1 trở lên, Node cần v4 trở lên. Sự khác biệt chỉ nằm ở cú pháp; khi tạo client, bạn chỉ cần truyền địa chỉ và khóa. Trước tiên là ví dụ không stream trên Python, đồng thời in usage để đối chiếu chi phí:

复制import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "写一条 20 字以内的发布公告标题。"}],
    max_tokens=100,
)
print(resp.choices[0].message.content)
print(resp.usage)

Ví dụ Node dùng stream, đây là cách phổ biến để tạo hiệu ứng gõ chữ trên giao diện người dùng. Khi stream kết thúc, máy chủ sẽ tự động gửi một chunk chứa usage, không cần thêm tham số:

复制import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.API_BASE ?? "https://api.llmzhongzhuan.com/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "列出三个命名服务端日志字段的好习惯。" }],
  stream: true,
  max_tokens: 300,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
process.stdout.write("\n");

Ví dụ Node dùng top-level await, yêu cầu tệp .mjs hoặc thiết lập "type": "module" trong package.json. Nếu môi trường chạy không hỗ trợ, bạn có thể bọc mã trong một hàm async.

LangChain: base_url của ChatOpenAI

LangChain không cần bộ điều hợp chuyên dụng, bạn chỉ cần dùng lớp ChatOpenAI từ gói langchain_openai và trỏ base_url đến endpoint của bạn.

复制import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
    temperature=0.7,
    max_tokens=500,
    timeout=60,
)

print(llm.invoke("把“服务已降级”改写成对用户友好的一句话。").content)

Hai lưu ý nhỏ. Thứ nhất, bạn nên đặt rõ max_tokens và timeout vì giá trị mặc định có thể không phù hợp với nghiệp vụ của bạn. Thứ hai, nếu bạn dùng gọi hàm trong chuỗi, trang này hỗ trợ công cụ định dạng OpenAI; bạn có thể dùng bind_tools của LangChain bình thường; khi stream, bạn chỉ cần xử lý từng chunk trong stream().

LlamaIndex: OpenAILike

Lớp OpenAI có sẵn của LlamaIndex sẽ kiểm tra xem tên mô hình có nằm trong danh sách chính thức không và báo lỗi nếu là tên tùy chỉnh. Lúc này bạn nên chuyển sang dùng OpenAILike từ gói llama-index-llms-openai-like; lớp này không kiểm tra và tên tham số cũng khác, địa chỉ gọi là api_base.

复制import os
from llama_index.llms.openai_like import OpenAILike

llm = OpenAILike(
    model="uncensored",
    api_base=os.environ.get("API_BASE", "https://api.llmzhongzhuan.com/v1"),
    api_key=os.environ["API_KEY"],
    is_chat_model=True,
    context_window=100000,
    max_tokens=500,
)

print(llm.complete("用一句话解释什么是幂等请求。"))

is_chat_model=True ở đây rất quan trọng vì nó buộc LlamaIndex dùng endpoint hội thoại thay vì endpoint hoàn văn cũ. Đặt context_window thành 100000 để LlamaIndex không cắt ngắn tài liệu của bạn theo mặc định vài nghìn token khi chia nhỏ ngữ cảnh.

Dify: nhà cung cấp tương thích OpenAI-API

Nền tảng trực quan như Dify không dùng mã nguồn mà cấu hình qua biểu mẫu. Văn bản giao diện có thể khác nhau giữa các phiên bản nhưng các bước cơ bản giống nhau:

1. Vào “Cài đặt”, tìm trang “Nhà cung cấp mô hình”, chọn “OpenAI-API-compatible” trong danh sách và nhấp vào thêm mô hình.
2. Chọn loại mô hình là “LLM”, điền tên mô hình là uncensored.
3. Điền khóa API của bạn vào trường API Key, điền https://api.llmzhongzhuan.com/v1 vào trường API endpoint URL.
4. Điền độ dài ngữ cảnh mô hình là 100000 và giới hạn token tối đa là 32000.
5. Nếu muốn dùng gọi hàm trong quy trình làm việc, hãy bật tùy chọn hỗ trợ gọi hàm; giữ nguyên chế độ stream.
6. Sau khi lưu, tạo một ứng dụng trò chuyện đơn giản, chọn mô hình vừa thêm và gửi một tin nhắn để xác nhận phản hồi hoạt động bình thường.

Nền tảng đôi khi gửi một yêu cầu kiểm tra khi lưu; nếu bước này thất bại, thường là do bạn thêm thừa đường dẫn vào địa chỉ hoặc khóa có khoảng trắng thừa. Nếu Dify của bạn chạy trong container, hãy đảm bảo container có thể truy cập tên miền ra internet.

Các tham số và cách triển khai cần kiểm tra trước khi đưa lên sản xuất

Việc khung chạy được chỉ là bước đầu; các tham số dưới đây bạn nên kiểm tra kỹ trước khi đưa lên sản xuất vì chúng ảnh hưởng trực tiếp đến chi phí và tỷ lệ lỗi.

• max_tokens: mặc định 2048; bạn nên tăng rõ ràng nếu cần xuất văn bản dài, tối đa 32,000. Lưu ý tổng đầu vào và đầu ra không được vượt quá 100,000 token, nếu không bạn sẽ nhận mã 400.
• timeout: yêu cầu xuất văn bản dài sẽ tốn nhiều thời gian hơn; trong trường hợp stream, bạn nên đặt thời gian chờ đọc lên trên 60 giây, còn không stream thì hãy ước tính theo thời gian xuất dài nhất.
• temperature / top_p / stop: các tham số lấy mẫu tiêu chuẩn này sẽ được chuyển tiếp; giá trị bạn đặt trong khung sẽ có hiệu lực ngay mà không cần bật thêm công tắc nào.
• Yêu cầu đồng thời: mỗi khóa giới hạn 300 yêu cầu mỗi phút; khi nhiều实例 dùng chung một khóa, giới hạn tốc độ được tính gộp, bạn không nên tính 300 cho mỗi实例.
• Tự động thử lại: cơ chế thử lại có sẵn của khung thường chỉ xử lý lỗi mạng; bạn cần tự thêm cơ chế hồiBacking-off cho mã 429 và 503, cách viết tham khảo bài viết về độ ổn định.

Triển khai vào container cũng tuân theo nguyên tắc “không chứa khóa trong ảnh”; công cụ điều phối sẽ tiêm khóa khi khởi động. Dưới đây là cách viết tối thiểu trong compose:

复制# docker-compose.yml 片段
services:
  app:
    image: your-app:latest
    environment:
      API_BASE: https://api.llmzhongzhuan.com/v1
      API_KEY: ${API_KEY}   # 从宿主机环境或 .env 读取，不写进镜像

Trên Kubernetes, bạn chuyển sang tham chiếu Secret, nguyên tắc không đổi. Bạn cũng nên chuẩn bị tài khoản hoặc khóa khác nhau cho từng môi trường, ví dụ một bộ cho phát triển, một bộ cho staging và một bộ cho production; như vậy nếu khóa của một môi trường bị lộ hoặc hết dư lượng, nó sẽ không ảnh hưởng đến môi trường sản xuất. Vì mỗi tài khoản chỉ có một khóa, bạn nên dùng nhiều tài khoản cho nhiều môi trường và nạp trước một số dư phù hợp cho từng tài khoản.

Cuối cùng là nhật ký. Nhiều khung in đầy đủ header khi gỡ lỗi, bao gồm Authorization. Hãy tắt chế độ gỡ lỗi hoặc ẩn khóa trong bộ lọc nhật ký. Ghi lại trường usage là thói quen tốt, giúp đối chiếu hóa đơn và phát hiện prompt dài bất thường.

Thứ tự kiểm tra khi gặp lỗi

90% vấn đề trong giai đoạn tích hợp tập trung vào một số điểm; bạn hãy kiểm tra theo thứ tự dưới đây để xử lý nhanh nhất:

1. 401：Khóa rỗng, sao chép kèm theo khoảng trắng, hoặc vẫn đang dùng khóa cũ sau khi đặt lại.
2. 404：Đường dẫn gốc thiếu /v1, hoặc đã thêm lặp lại /chat/completions.
3. 402：Mã lỗi no_credit cho thấy bạn đã hết dư lượng hoặc hết hạn tín dụng dùng thử miễn phí, bạn cần nạp tiền vào tín dụng trả trước.
4. 400：Nguyên nhân phổ biến là tổng số token đầu vào vượt quá 100,000 khi đặt max_tokens, hoặc kích thước request body vượt quá 8 MB.
5. 429 / 503: cái đầu tiên là giới hạn tốc độ 300 lần mỗi phút, cái thứ hai là upstream_busy, hãy đợi vài giây rồi thử lại, cách làm cụ thể xem thực tiễn ổn định.

Một vấn đề dễ bị bỏ qua khác là môi trường mạng. Mạng nội bộ công ty, phần mềm proxy hoặc quy tắc nhóm bảo mật có thể khiến việc phân giải tên miền thành công nhưng không thiết lập được kết nối HTTPS, biểu hiện là bị treo lâu rồi hết thời gian chờ thay vì trả về mã lỗi rõ ràng. Trong trường hợp này, hãy dùng curl để truy cập /v1/models trên cùng một máy; nếu truy cập được thì vấn đề nằm ở lớp ứng dụng, nếu không thì hãy kiểm tra proxy và tường lửa. Ghi lại quy trình khắc phục sự cố vào tài liệu nhóm để đồng nghiệp mới khi tích hợp sẽ tránh được những sai lầm không đáng có.

Khi ba giá trị đều đúng nhưng vẫn thất bại, hãy dùng curl để yêu cầu trực tiếp một lần trước, loại trừ vấn đề của chính framework. Nếu muốn tìm hiểu trước xem trung gian thực sự làm gì, bạn có thể xem lại nguyên lý trung gian.