# Tại sao đầu ra JSON có cấu trúc bị hỏng sau khi chuyển đổi API LLM? > JSON có cấu trúc thường hỏng sau khi di chuyển API LLM vì các stack cũ và mới áp đặt những hợp đồng khác nhau. Hãy so sánh schema yêu cầu, chế độ phản hồi, hành vi streaming, envelope gọi công cụ, phản hồi từ chối và quy tắc xác thực trước khi đổ lỗi cho prompt. Một cuộc di trú thay đổi nhiều hơn tên máy chủ. Nó có thể thay đổi mô hình, cách tuần tự hóa SDK, các từ khóa lược đồ được hỗ trợ, thứ tự sự kiện truyền phát, giá trị lấy mẫu mặc định, hành vi an toàn và vị trí chính xác của payload được tạo. Do đó, một yêu cầu trông có vẻ tương đương trong mã ứng dụng có thể đại diện cho một hợp đồng khác trên đường truyền. Chẩn đoán nhanh nhất là lưu một yêu cầu thất bại và phản hồi chưa sửa đổi của nó từ cả hai nhà cung cấp. So sánh khác biệt nội dung HTTP thực tế, không phải các đối tượng bao bọc mà SDK của bạn hiển thị. Việc so sánh đó thường tiết lộ liệu lỗi xảy ra trước khi tạo, trong khi tạo, hay trong khi ứng dụng của bạn trích xuất và xác thực kết quả. ## Phân biệt lỗi cú pháp với lỗi hợp đồng "JSON hỏng" có thể mô tả một số khiếm khuyết khác nhau. Việc coi chúng là một vấn đề dẫn đến việc chỉnh sửa prompt để che giấu nguyên nhân thực sự. * Lỗi cú pháp tạo ra văn bản mà trình phân tích cú pháp JSON không thể đọc được. * Lỗi lược đồ tạo ra JSON hợp lệ nhưng có khóa, kiểu, cấu trúc lồng nhau hoặc giá trị enum sai. * Lỗi trích xuất xảy ra khi dữ liệu có cấu trúc hợp lệ nằm trong một trường phản hồi khác. * Lỗi truyền phát xảy ra khi các phần nhỏ được phân tích cú pháp như tài liệu hoàn chỉnh. * Lỗi từ chối hoặc cắt ngắn thay thế đối tượng mong đợi bằng thông báo an toàn hoặc payload không đầy đủ. * Lỗi gọi công cụ trả về đối số trong một phong bì công cụ trong khi ứng dụng mong đợi văn bản trợ lý. Ghi nhật ký các loại này riêng biệt. Một ngoại lệ trình phân tích cú pháp, một trường bắt buộc bị thiếu và lỗi `400` cấp API không nên dùng chung một bộ đếm thử lại chung. ## So sánh hai hợp đồng yêu cầu Bắt đầu với ma trận di trú từng trường. Những tên trông giống nhau không phải lúc nào cũng có nghĩa giống nhau. | Khu vực hợp đồng | Ngăn xếp cũ | Ngăn xếp mới | Câu hỏi kiểm tra | |---|---|---|---| | Chế độ đầu ra | Đối tượng JSON | Đối tượng ràng buộc lược đồ | Nó chỉ đảm bảo cú pháp hay toàn bộ lược đồ? | | Vị trí lược đồ | Tham số công cụ | Định dạng phản hồi | Lược đồ có được gắn vào trường yêu cầu chính xác không? | | Tính nghiêm ngặt | Ngầm định | Cờ rõ ràng | Có phải bật chế độ nghiêm ngặt không? | | Từ khóa không được hỗ trợ | Bị bỏ qua | Bị từ chối | Các hợp nhất, định dạng, mặc định hoặc tham chiếu có được chấp nhận không? | | Khóa bổ sung | Được phép | Bị chặn | `additionalProperties` có được xử lý nhất quán không? | | Truyền phát | Delta văn bản | Sự kiện có kiểu | Sự kiện nào chứa đối tượng đã hoàn thành? | | Từ chối | Văn bản trợ lý | Trường chuyên dụng | Trình trích xuất có thể phân biệt từ chối với đầu ra không? | Ghi lại yêu cầu đã tuần tự hóa cuối cùng sau khi SDK xử lý. Các giá trị mặc định do máy khách cũ đưa vào có thể biến mất trong quá trình di trú. Điều ngược lại cũng xảy ra: SDK mới có thể thêm cờ nghiêm ngặt hoặc đổi tên trường định dạng phản hồi mà không có lỗi ứng dụng rõ ràng. ## Giảm lược đồ trước khi thay đổi prompt Kiểm tra lược đồ nhỏ nhất có thể trước. Bắt đầu với một chuỗi bắt buộc và không có nhánh tùy chọn. Thêm số nguyên, mảng, đối tượng lồng nhau, enum và cấu trúc điều kiện từng cái một. Điều này cô lập các tính năng không được hỗ trợ nhanh hơn nhiều so với việc viết lại nhiều lần một prompt sản xuất. Ví dụ, một đường cơ sở di động có thể trông như thế này: ```json { "type": "object", "properties": { "decision": { "type": "string", "enum": ["approve", "review", "reject"] }, "reason": { "type": "string" } }, "required": ["decision", "reason"], "additionalProperties": false } ``` Nếu điều này hoạt động, đường truyền và đường thực thi cơ bản là ổn. Nếu lược đồ sản xuất thất bại sau khi thêm một tính năng, bạn có một câu hỏi tương thích cụ thể thay vì một vấn đề chất lượng mô hình mơ hồ. ## Kiểm tra nơi payload có cấu trúc nằm Việc di trú nhà cung cấp thường phá vỡ mã trích xuất. Một ngăn xếp có thể trả về JSON trong một tin nhắn trợ lý, một ngăn xếp khác trong thuộc tính tiện lợi đã phân tích cú pháp, và một ngăn xếp khác dưới dạng đối số công cụ được chuỗi hóa. Truyền phát có thể hiển thị một chuỗi các sự kiện có kiểu thay vì delta văn bản thông thường. Tạo một kết quả nội bộ đã chuẩn hóa trước khi phần còn lại của ứng dụng nhìn thấy phản hồi: ```ts type StructuredResult = { data: T | null; raw: unknown; refusal: string | null; finishReason: string | null; validationErrors: string[]; }; ``` Giữ `raw` trong thời gian di trú. Đó là bằng chứng cần thiết để phân biệt khiếm khuyết đầu ra mô hình với khiếm khuyết bộ chuyển đổi. Loại bỏ nội dung nhạy cảm trước khi lưu nhật ký và đặt thời gian lưu trữ phù hợp với ứng dụng của bạn. ## Không phân tích cú pháp một luồng chưa hoàn thành Một tài liệu JSON thường không hợp lệ cho đến khi byte cuối cùng của nó đến. Việc phân tích cú pháp mọi delta văn bản sẽ tạo ra các lỗi dự kiến trông giống như lỗi sản xuất. Hoặc đệm toàn bộ đầu ra, sử dụng trình phân tích cú pháp JSON tăng dần được nhà cung cấp hỗ trợ, hoặc tiêu thụ một sự kiện được ghi lại đại diện cho phản hồi có cấu trúc đã hoàn thiện. Bài kiểm tra truyền phát của bạn nên bao gồm nhiều hơn đường dẫn thành công: * chuỗi bị chia cắt giữa các phần; * dấu ngoặc kép được thoát và ký tự Unicode; * mảng có nhiều phần tử; * ngắt kết nối trước dấu ngoặc nhọn đóng; * một sự kiện từ chối; * một đối tượng cuối cùng hợp lệ theo sau là siêu dữ liệu sử dụng; * đối số công cụ được gửi trong nhiều delta. Xử lý gián đoạn mạng như một quá trình tạo chưa hoàn chỉnh, không phải là đầu ra mô hình bị hỏng. Thử lại có thể an toàn cho yêu cầu phân loại chỉ đọc, nhưng có thể không an toàn nếu kết quả gây ra tác dụng phụ bên ngoài. ## Xác thực hai lần, nhưng sửa chữa cẩn thận Nhà cung cấp có thể thực thi một lược đồ, nhưng ứng dụng của bạn vẫn nên xác thực kết quả đã chuẩn hóa tại ranh giới tin cậy của nó. Điều này bảo vệ bạn khỏi lỗi bộ chuyển đổi, thoái lui tính năng và các giả định mà nhà cung cấp chưa bao giờ hứa. Một trình tự thực tế là: 1. Xác nhận yêu cầu HTTP thành công. 2. Phát hiện từ chối, cắt ngắn hoặc hoàn thành gọi công cụ một cách rõ ràng. 3. Trích xuất payload có cấu trúc đã hoàn thành. 4. Phân tích cú pháp nó một lần. 5. Xác thực nó với phiên bản lược đồ của ứng dụng. 6. Từ chối các giá trị không xác định hoặc không an toàn trước khi logic nghiệp vụ chạy. Tránh vòng lặp "sửa JSON này" không giới hạn. Một mô hình sửa chữa có thể thay đổi ý nghĩa trong khi làm cho cú pháp hợp lệ. Nếu việc sửa chữa được chấp nhận, hãy giới hạn nó trong một lần thử, cung cấp các lỗi xác thực, giữ nguyên đầu ra gốc và xác thực lại đối tượng đã sửa. Đối với các hành động có tác động cao, hãy gửi trường hợp để xem xét thay vì. ## Xây dựng bộ tái hiện di trú Trước khi định tuyến lưu lượng sản xuất, hãy tập hợp một tập dữ liệu nhỏ gọn từ các hình dạng yêu cầu thực tế. Loại bỏ dữ liệu cá nhân hoặc bí mật, sau đó bao gồm các trường hợp kiểm tra ranh giới của hợp đồng của bạn. | Nhóm trường hợp | Nội dung cần bao gồm | Điều kiện đạt | |---|---|---| | Bình thường | Đầu vào ngắn phổ biến | Đối tượng hợp lệ với các giá trị mong đợi | | Trường tùy chọn | Các biến thể thiếu và có mặt | Hành vi bắt buộc và tùy chọn khớp với hợp đồng | | Mơ hồ | Đầu vào xung đột hoặc không đặc tả đầy đủ | Đối tượng hợp lệ cộng với trạng thái không chắc chắn được phép | | Ngữ cảnh dài | Gần mức tối đa bình thường của ứng dụng | Không cắt ngắn và trích xuất hợp lệ | | Đối kháng | Văn bản yêu cầu mô hình bỏ qua lược đồ | Lược đồ vẫn nguyên vẹn | | Từ chối | Yêu cầu bị cấm hoặc không an toàn | Từ chối được phát hiện mà không gây nhầm lẫn cho trình phân tích cú pháp | | Truyền phát | Ranh giới phần và ngắt kết nối | Chỉ payload đã hoàn thành mới đến xác thực | Chạy cả hai nhà cung cấp với các tham số ổn định và ghi lại tỷ lệ hợp lệ, thỏa thuận ngữ nghĩa, tỷ lệ từ chối, tỷ lệ cắt ngắn, độ trễ và số lần thử lại. Không phải lúc nào cũng mong đợi sự bình đẳng ngữ nghĩa chính xác, nhưng tính hợp lệ của lược đồ phải là một cổng cứng. ## Đặt tính tương thích phía sau một bộ chuyển đổi Đừng để các loại phản hồi của nhà cung cấp rò rỉ khắp toàn bộ cơ sở mã. Một bộ chuyển đổi nhỏ nên sở hữu việc xây dựng yêu cầu, kiểm tra khả năng lược đồ, trích xuất phản hồi, lý do kết thúc, trường sử dụng và chuẩn hóa lỗi. Phần còn lại của ứng dụng nên tiêu thụ một giao diện nội bộ duy nhất. Một cổng tương thích OpenAI như [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=structured-json-output-after-llm-api-migration) có thể giảm công việc tích hợp lặp lại khi một ứng dụng sử dụng mô hình văn bản, hình ảnh và video. Tính tương thích ở lớp truyền tải là hữu ích, nhưng nó không loại bỏ việc kiểm thử cấp mô hình. Giữ cờ khả năng cho đầu ra có cấu trúc, công cụ, truyền phát và các tính năng lược đồ thay vì giả định mọi mô hình đằng sau một điểm cuối tương thích đều hoạt động giống hệt nhau. Đánh phiên bản cho bộ chuyển đổi và lược đồ cùng nhau. Khi lược đồ thay đổi, hãy lưu phiên bản lược đồ với đầu ra để các dịch vụ hạ nguồn biết chúng nhận được hợp đồng nào. ## Sử dụng triển khai theo giai đoạn với các điều kiện dừng rõ ràng Bắt đầu với tái hiện ngoại tuyến, sau đó lưu lượng bóng, sau đó một tỷ lệ nhỏ trực tiếp. Đừng chỉ dựa vào thành công tổng hợp. Tỷ lệ hợp lệ 99% vẫn có thể không chấp nhận được nếu 1% thất bại tập trung trong các yêu cầu thanh toán, kiểm duyệt hoặc ủy quyền. Xác định các điều kiện dừng trước khi kiểm thử: * bất kỳ enum không an toàn nào đến được logic nghiệp vụ; * tỷ lệ hợp lệ lược đồ giảm xuống dưới đường cơ sở hiện tại; * xử lý từ chối trở nên mơ hồ; * cắt ngắn tăng vượt quá ngưỡng đã thống nhất; * thử lại làm tăng chi phí hoặc độ trễ vượt quá ngân sách của ứng dụng; * phản hồi thô không thể đối chiếu với đầu ra đã chuẩn hóa. Quay lại thông qua cấu hình định tuyến thay vì triển khai mã khẩn cấp khi có thể. Giữ bộ chuyển đổi cũ khả dụng cho đến khi đường dẫn mới vượt qua cả tải cao điểm và các lớp đầu vào hiếm gặp. ## Điểm mấu chốt Các lỗi JSON có cấu trúc sau khi di trú API LLM thường là do hợp đồng không khớp, lỗi trích xuất hoặc logic truyền phát chưa hoàn chỉnh hơn là bằng chứng cho thấy mô hình mới không thể tuân theo hướng dẫn. So sánh khác biệt payload trên đường truyền, thu nhỏ lược đồ, chuẩn hóa phản hồi, xác thực tại ranh giới ứng dụng và tái hiện một tập dữ liệu đại diện trước khi chuyển lưu lượng. Một API tương thích có thể đơn giản hóa việc di chuyển, nhưng các bài kiểm tra khả năng rõ ràng vẫn là cách đáng tin cậy để bảo vệ hành vi sản xuất. ## FAQ ### Tại sao cùng một prompt JSON lại hoạt động với mô hình này nhưng lại thất bại với mô hình khác? Cách diễn đạt prompt chỉ là một lớp. Các mô hình và nhà cung cấp khác nhau ở chế độ JSON gốc, hỗ trợ schema, token hóa, hành vi từ chối và mức độ tuân thủ nghiêm ngặt các ràng buộc. ### Chế độ JSON có giống với thực thi JSON Schema không? Không. Chế độ JSON có thể chỉ đảm bảo JSON hợp lệ về mặt cú pháp, trong khi thực thi schema còn ràng buộc các khóa, kiểu, trường bắt buộc và đôi khi cả thuộc tính bổ sung. ### Tôi có nên phân tích cú pháp JSON được truyền theo luồng từng token một không? Thường thì không. Hãy đệm toàn bộ payload có cấu trúc hoặc dùng các sự kiện structured-streaming đã được nhà cung cấp ghi trong tài liệu, rồi xác thực sau sự kiện cuối cùng. ### API tương thích OpenAI có thể loại bỏ công việc migration không? Nó có thể giảm các thay đổi về truyền tải và SDK, nhưng bạn vẫn cần xác minh các tính năng schema riêng cho mô hình, lý do kết thúc, định dạng gọi công cụ và hành vi lỗi. ### Điều gì nên xảy ra khi xác thực thất bại? Ghi lại phản hồi thô, phân loại lỗi, chỉ thử lại các trường hợp tạm thời an toàn và định tuyến sửa chữa tất định qua một bước xác thực có giới hạn thay vì âm thầm chấp nhận dữ liệu sai định dạng. ### Bài kiểm thử tiền sản xuất nhanh nhất là gì? Phát lại một tập ngữ liệu cố định gồm các yêu cầu thông thường, mơ hồ, đối kháng, từ chối, ngữ cảnh dài và truyền phát đối với cả hai ngăn xếp và so sánh các đầu ra đã được xác thực theo từng trường.