Cách kiểm tra và gỡ lỗi yêu cầu API Grok 4.6 (Streaming, Tool Calls và Lỗi)

Grok 4.6 được xây dựng cho các tác nhân hoạt động liên tục, vì vậy lỗi tích hợp thường xuất hiện ở các điểm khó gỡ lỗi nhất: phản hồi stream dừng giữa chừng khi đang truyền token, payload lời gọi công cụ gần hợp lệ nhưng không phân tích được, hoặc giới hạn tỷ lệ chỉ xuất hiện khi có tải sản xuất. Tài liệu xAI cho biết API chấp nhận gì; bài viết này tập trung vào cách kiểm thử, xác thực yêu cầu, gỡ lỗi stream, xử lý lỗi, và giả lập phản hồi Grok để CI không tiêu tốn token.

Dùng thử Apidog ngay hôm nay

Mọi ví dụ sử dụng Apidog làm môi trường làm việc để xem SSE, quản lý bí mật theo môi trường, xác nhận phản hồi và tạo mock server trong một nơi. Bạn vẫn có thể áp dụng quy trình này với curl hoặc công cụ tự xây dựng, nhưng một workspace thống nhất giúp giảm đáng kể thao tác khi tái tạo lỗi.

TL;DR

• Lưu https://api.x.ai/v1 và XAI_API_KEY dưới dạng biến môi trường; không ghi cứng khóa vào request hoặc repository.
• Gỡ lỗi stream bằng cách quan sát từng khối SSE theo thời gian thực để phân biệt lỗi server/network với lỗi client.
• Với tool calling, luôn xác thực tool_calls[].function.arguments: phải parse được JSON và khớp schema.
• Không retry 400, 401, 404; retry 429 bằng exponential backoff có jitter, và retry 5xx với số lần giới hạn.
• Ghi log usage trên mọi phản hồi để theo dõi token và phát hiện tăng chi phí sớm.
• Mock endpoint Grok trong CI; chỉ chạy kiểm thử API thật theo lịch trình hoặc trước khi phát hành.
• Chuyển các request gỡ lỗi thành test scenario tự động và chạy lại được bằng một lệnh.

Thiết lập workspace trước khi gỡ lỗi

Các lệnh curl ad-hoc đủ cho lần gọi đầu tiên, nhưng nhanh chóng trở nên khó quản lý khi bạn cần so sánh nhiều biến thể request hoặc tái tạo lỗi theo môi trường.

Thiết lập trong Apidog:

1. Tạo project, ví dụ: Tích hợp Grok 4.6.
2. Tạo environment xai-dev.
3. Thêm các biến:

   base_url = https://api.x.ai/v1
   api_key = <khóa của bạn>

Đánh dấu api_key là bí mật.

1. Tạo request:

   POST {{base_url}}/chat/completions
   Authorization: Bearer {{api_key}}
   Content-Type: application/json

1. Nhân bản environment thành xai-prod, rồi thay bằng khóa production.

Cùng một request nhưng tách phạm vi biến giúp tránh việc thử nghiệm của developer vô tình sử dụng hạn mức production.

Nếu chưa có khóa API, hãy xem hướng dẫn khởi đầu nhanh API Grok 4.6 để thiết lập console.x.ai và gửi request đầu tiên bằng curl, Python hoặc JavaScript.

Xác thực request trước khi đổ lỗi cho mô hình

Khi đầu ra không như mong đợi, hãy kiểm tra request theo thứ tự sau.

1. Kiểm tra model ID

Với API gốc, dùng:

{
  "model": "grok-4-6"
}

Một số nhà cung cấp trung gian dùng ID khác. Ví dụ, OpenRouter dùng:

{
  "model": "x-ai/grok-4.6"
}

Nếu nhận 404, hãy xác minh model ID và endpoint trước khi kết luận rằng dịch vụ gặp sự cố.

2. Kiểm tra tham số

Các giá trị như temperature ngoài phạm vi hoặc max_tokens không phù hợp với ngữ cảnh thường trả về 400.

Ví dụ request cơ bản:

{
  "model": "grok-4-6",
  "messages": [
    {
      "role": "system",
      "content": "Trả lời ngắn gọn, có cấu trúc."
    },
    {
      "role": "user",
      "content": "Giải thích cách hoạt động của SSE."
    }
  ],
  "max_tokens": 1000
}

Khi nhận 400, hãy đọc thông báo lỗi trước khi thay đổi prompt, model hoặc cơ chế retry.

3. Kiểm tra cấu trúc messages

Mảng messages hợp lệ về mặt cú pháp vẫn có thể tạo ra đầu ra kém chất lượng nếu:

• Có message rỗng không chủ ý.
• System prompt bị lặp.
• Thứ tự hội thoại không hợp lý.
• Context của tác nhân chứa dữ liệu cũ hoặc không còn liên quan.

Đây là loại lỗi khó phát hiện vì API vẫn trả về 200.

4. Theo dõi ngân sách context

Grok 4.6 có cửa sổ ngữ cảnh 500K token, nhưng vẫn là hữu hạn. Nhật ký tác nhân dài cộng với max_tokens lớn có thể làm đầy cửa sổ và dẫn đến cắt bớt phản hồi.

Ghi log dữ liệu usage từ phản hồi:

{
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

Thiết lập cảnh báo khi prompt_tokens tăng dần đến ngưỡng nội bộ của bạn thay vì chờ đến khi phản hồi bị cắt bớt.

Apidog có thể xác thực cấu trúc request trước khi gửi, giúp phát hiện kiểu dữ liệu sai hoặc thiếu trường bắt buộc mà không cần gọi API.

Gỡ lỗi stream SSE

Phản hồi Grok 4.6 có thể được stream dưới dạng server-sent events (SSE). Với câu trả lời tác nhân dài, hàng nghìn token là bình thường, nên cần phân biệt rõ stream chậm với stream bị lỗi.

Bật stream trong request:

{
  "model": "grok-4-6",
  "messages": [
    {
      "role": "user",
      "content": "Phân tích từng bước cách triển khai một API client."
    }
  ],
  "stream": true
}

Ba lỗi stream phổ biến nhất:

1. Token dừng giữa phản hồi

Trong terminal, không dễ biết mô hình đang xử lý hay stream thực sự đã dừng. Trong chế độ xem SSE của Apidog, kiểm tra xem các khối có tiếp tục đến hay không:

• Không còn khối SSE mới: vấn đề có thể nằm ở server, mạng, proxy hoặc timeout.
• Khối vẫn đến nhưng UI ứng dụng không cập nhật: vấn đề nằm ở client, buffer hoặc logic tiêu thụ stream.

Phân biệt này giúp khoanh vùng lỗi ngay từ đầu.

2. Stream kết thúc sớm nhưng không báo lỗi

Kiểm tra finish_reason của khối cuối cùng:

• length: đã chạm max_tokens; tăng giới hạn nếu tác vụ cần câu trả lời dài hơn.
• stop: mô hình đã hoàn thành phản hồi.

Đừng chỉ kiểm tra HTTP status. Một stream trả về 200 vẫn có thể bị cắt bớt do giới hạn token.

3. Proxy đệm SSE

Nếu stream hoạt động trên máy local nhưng bị treo ở staging hoặc production, hãy kiểm tra reverse proxy.

Với nginx, đường dẫn stream cần tắt buffering:

location /api/chat {
  proxy_buffering off;
}

Gửi cùng request từ Apidog đến môi trường local và qua gateway. Nếu local stream bình thường nhưng gateway không stream, lỗi nằm ở hạ tầng thay vì xAI.

Tool calling: điểm dễ vỡ nhất của vòng lặp tác nhân

Grok 4.6 hướng đến tác nhân, vì vậy function calling thường là phần chịu tải cao nhất. Đừng coi tool call là dữ liệu đáng tin cậy chỉ vì HTTP response thành công.

Các lỗi cần xử lý:

1. arguments không parse được

tool_calls[].function.arguments là chuỗi JSON, không phải object JSON.

Ví dụ xử lý phòng vệ trong JavaScript:

function parseToolArguments(rawArguments) {
  try {
    return JSON.parse(rawArguments);
  } catch (error) {
    console.error("Không thể parse tool arguments", {
      rawArguments,
      error: error.message,
    });

    throw new Error("TOOL_ARGUMENTS_INVALID_JSON");
  }
}

Theo dõi tỷ lệ parse lỗi. Nếu tỷ lệ này tăng, hãy kiểm tra thay đổi ở prompt, schema hoặc cách lắp ráp dữ liệu stream.

2. JSON hợp lệ nhưng sai schema

JSON parse thành công không có nghĩa là dữ liệu có thể gọi tool.

Ví dụ, tool cần:

{
  "city": "Hà Nội",
  "days": 3
}

Nhưng mô hình có thể trả về:

{
  "city": "Hà Nội",
  "days": "ba"
}

Luôn xác thực object đã parse theo schema của tool trước khi thực thi.

Quy trình an toàn:

Nhận tool call
→ Ghép các mảnh stream
→ Parse JSON
→ Validate schema
→ Kiểm tra tool name trong allowlist
→ Gọi tool

3. Tool name không tồn tại

Không gọi trực tiếp tool bằng tên do mô hình trả về. Dùng allowlist:

const tools = {
  get_weather: getWeather,
  search_docs: searchDocs,
};

function resolveTool(name) {
  const tool = tools[name];

  if (!tool) {
    throw new Error(`UNKNOWN_TOOL: ${name}`);
  }

  return tool;
}

Việc từ chối rõ ràng tool không xác định an toàn hơn để KeyError hoặc lỗi runtime làm sập vòng lặp tác nhân.

4. Parse trước khi ghép đủ dữ liệu stream

Trong stream, đối số tool call có thể đến theo nhiều mảnh. Nếu parse từng mảnh ngay khi nhận được, bạn sẽ thấy lỗi JSON giả và dễ nhầm rằng mô hình tạo JSON hỏng.

Chỉ parse sau khi đã ghép hoàn chỉnh chuỗi arguments.

Trong Apidog, lưu một request trả về tool call rồi thêm assertions cho:

• Tool name thuộc tập tên được phép.
• Chuỗi arguments parse được.
• Object sau parse khớp schema.

Chạy request nhiều lần, không chỉ một lần. Tính không xác định của LLM có thể khiến tỷ lệ lỗi 10% không xuất hiện trong một lượt chạy đơn lẻ.

Nếu hệ thống dùng MCP thay vì function calling trực tiếp, nguyên tắc vẫn tương tự. Xem thêm hướng dẫn kiểm thử máy chủ MCP với Apidog.

Chính sách lỗi, retry và giới hạn tỷ lệ

Một tích hợp production cần chính sách rõ ràng cho từng nhóm lỗi.

Mã trạng thái	Ý nghĩa	Chính sách
400	Request sai định dạng	Không retry. Ghi log và sửa request. Retry request lỗi chỉ tạo vòng lặp không hồi kết.
401	Khóa sai hoặc thiếu	Không retry. Kiểm tra biến môi trường và khóa trong console.
404	Sai model hoặc endpoint	Không retry. Xác minh lại bằng /v1/models.
429	Giới hạn tỷ lệ hoặc hạn mức	Retry bằng exponential backoff có jitter; tuân thủ Retry-After nếu có.
5xx	Lỗi phía server	Retry tối đa 3 lần với backoff, sau đó đánh dấu tác vụ thất bại rõ ràng.
Timeout	Phản hồi lâu hoặc lỗi mạng	Ưu tiên stream; đặt client timeout theo phút thay vì giây cho tác vụ tác nhân.

Ví dụ exponential backoff có jitter:

function getRetryDelay(attempt) {
  const baseDelayMs = 500;
  const maxDelayMs = 10_000;

  const exponentialDelay = Math.min(
    baseDelayMs * 2 ** attempt,
    maxDelayMs
  );

  const jitter = Math.random() * 250;

  return exponentialDelay + jitter;
}

Nguyên tắc retry:

const retryableStatuses = new Set([429, 500, 502, 503, 504]);

function shouldRetry(status, attempt) {
  return retryableStatuses.has(status) && attempt < 3;
}

Hai lưu ý quan trọng:

1. Sau khi có bản phát hành mới, tải cao có thể khiến 429 và 5xx tạm thời phổ biến hơn. Hãy triển khai backoff trước khi demo hoặc đưa lưu lượng lớn vào hệ thống.
2. Ghi log usage trên mọi response. Với mức giá 2/6 đô la cho mỗi triệu token, chi phí có thể hợp lý ở từng request, nhưng vòng lặp tác nhân sẽ nhân số lượt gọi lên nhanh chóng.

Để hiểu thêm về cấu trúc chi phí, xem phân tích giá Grok.

Mock Grok trong CI, tách kiểm thử API thật

CI không nên gọi model trực tiếp trên mỗi commit.

Một integration test tác nhân có thể thực hiện 30 lời gọi Grok thật. Điều đó gây tốn chi phí, chậm và có thể thất bại ngẫu nhiên khi nhà cung cấp gặp sự cố. Khi test trở nên không ổn định, đội ngũ thường sẽ bỏ qua chúng.

Tách kiểm thử thành hai nhóm.

1. Mock để kiểm thử logic trên mỗi commit

Dùng mock server của Apidog để trả về response có hình dạng như Grok thực tế:

• Một completion đơn giản.
• Một response có tool call.
• Lỗi 429.
• Response 5xx.
• Stream bị cắt bớt với finish_reason: "length".
• Tool arguments không parse được.
• Tool arguments hợp lệ nhưng vi phạm schema.

Các test này nên xác minh:

- Logic retry
- Tôn trọng Retry-After
- Parse JSON
- Validate schema
- Kết thúc vòng lặp tác nhân
- Xử lý stream bị ngắt
- Ghi log usage

Đây là các test nhanh, xác định và không tốn token.

2. Chạy kiểm thử API thật theo lịch trình

Chạy live test hàng đêm hoặc trước khi phát hành để phát hiện:

• Thay đổi hành vi từ nhà cung cấp.
• Thay đổi định dạng tool calling.
• Giới hạn tỷ lệ mới.
• Vấn đề xác thực hoặc model ID.

Trong Apidog, cùng một test scenario có thể trỏ tới:

• Mock environment trong CI.
• xai-dev cho live test theo lịch trình.

Cùng assertions, hai target khác nhau.

Nếu chạy test từ terminal hoặc pipeline, Apidog CLI có thể thực thi các scenario mà không cần UI.

Checklist trước khi đưa vào production

Trước khi đưa lưu lượng Grok 4.6 vào hoạt động, kiểm tra các mục sau:

• [ ] API key nằm trong biến môi trường, tách riêng dev và prod, không xuất hiện trong version control.
• [ ] Stream xử lý được finish_reason: "length", sự kiện dừng và buffering từ proxy.
• [ ] Tool arguments được ghép hoàn chỉnh trước khi parse.
• [ ] Tool arguments được parse phòng vệ và validate schema trong mọi lần gọi.
• [ ] Tool name được kiểm tra bằng allowlist.
• [ ] Chính sách retry cho 429 và 5xx đã được triển khai và kiểm thử bằng mock.
• [ ] usage được ghi log trên mọi request và có cảnh báo khi chi phí mỗi tác vụ tăng.
• [ ] CI chạy bằng mock; live test chạy theo lịch trình.
• [ ] Toàn bộ test suite có thể chạy lại bằng một lệnh khi có bản phát hành model mới.

Câu hỏi thường gặp

Làm cách nào để gỡ lỗi phản hồi stream Grok 4.6 bị treo?

Tái tạo request trong chế độ xem SSE của Apidog. Nếu các khối SSE ngừng đến, hãy kiểm tra server, network, proxy và timeout. Nếu khối vẫn đến nhưng ứng dụng không hiển thị, hãy kiểm tra buffer, async handling và logic tiêu thụ stream ở client.

Tại sao tool call của Grok 4.6 đôi khi không parse được?

arguments là chuỗi JSON, có thể không hợp lệ hoặc chưa hoàn chỉnh nếu bạn đang nhận stream. Hãy ghép tất cả mảnh dữ liệu trước khi parse, bọc JSON.parse() trong try/catch, rồi validate object kết quả theo schema.

Có nên gọi API Grok thật trong mọi test không?

Không. Mock endpoint trên mỗi commit để CI nhanh, ổn định và miễn phí. Chỉ gọi API thật theo lịch trình, chẳng hạn hàng đêm hoặc trước khi phát hành, để phát hiện thay đổi từ nhà cung cấp.

Quy trình này có áp dụng cho API LLM khác không?

Có. Vì API Grok tương thích với OpenAI, bạn có thể giữ cùng cấu trúc project và dùng một environment cho mỗi nhà cung cấp. Cách này phù hợp để kiểm thử song song Grok, Claude và GPT-5.6.