JSON thành Markdown: Biến kết xuất lồng nhau thành thứ bạn thực sự có thể đọc
JSON là một định dạng máy được con người chấp nhận. Nó ổn ở độ sâu ba cấp độ. Ở độ sâu tám tầng, với một mảng gồm 400 đồ vật ở giữa, bạn đang di chuyển qua một bức tường có các thanh giằng cố gắng tìm ra dấu ngoặc đóng nào thuộc về cái gì. Bất kỳ ai đã mở phản hồi API thô trong một tab trình duyệt biết cảm giác.
Chuyển đổi JSON tới Markdown lấy cây đó và thể hiện lại nó dưới dạng tài liệu.
Các phím đối tượng trở thành tiêu đề. Các đối tượng lồng nhau trở thành các phần lồng nhau. Mảng các bản ghi tương tự trở thành
các bảng bạn có thể quét bằng mắt thay vì Ctrl+F chìa khóa. Thả một .json
vào công cụ trên và bạn sẽ có nó sau vài giây — miễn phí, không cần đăng ký, giới hạn 50 MB,
không có gì giữ ở phía chúng tôi.
Điều gì xảy ra với cấu trúc
Quá trình chuyển đổi là một bước đi xuống cây và mỗi cấu trúc JSON ánh xạ lên một Markdown:
- Các đối tượng trở thành các phần. Một khóa cấp cao nhất như
customerbiến thành một tiêu đề và mọi thứ bên dưới nó đều nằm bên dưới tiêu đề đó. Độ sâu trở thành cấp độ tiêu đề, do đó hệ thống phân cấp mà bạn phải suy ra từ thụt lề giờ đây có thể nhìn thấy được trong nháy mắt. - Các cặp khóa/giá trị vô hướng trở thành các dòng được gắn nhãn.
"status": "active"đọc như trạng thái: hoạt động. Dấu ngoặc kép, dấu hai chấm và dấu phẩy cuối cùng đều biến mất, và với chúng khoảng một phần ba số ký tự trong một tệp thông thường. - Mảng vô hướng trở thành danh sách dấu đầu dòng. Danh sách thẻ hoặc ID không còn trông như thế nữa một cấu trúc dữ liệu và bắt đầu trông giống như một danh sách.
- Mảng các đối tượng đồng nhất trở thành bảng. Đây là cái lớn, và nó có được phần riêng bên dưới.
- Giá trị trống và null. Một trường được đặt thành
null,""hoặc[]hầu như không mang thông tin nhưng tính phí mã thông báo trên mỗi bản ghi mà nó xuất hiện. Việc làm phẳng sẽ loại bỏ tiếng ồn đó thay vì lặp lại 500 lần.
Điều mà JSON thô không tốt đối với người đọc cũng chính là điều mà nó làm tốt đối với trình phân tích cú pháp: mỗi bản ghi trình bày lại mọi phím. JSON được lồng sâu ẩn hình dạng của nó đằng sau dấu câu. Markdown đặt hình dạng trên bề mặt.
Mảng các đối tượng đồng nhất là trường hợp lý tưởng
Nếu JSON của bạn là danh sách các bản ghi có chung khóa - đơn hàng, người dùng, sản phẩm, nhật ký mục nhập, kết quả tìm kiếm — bạn nhận được kết quả tốt nhất có thể: một bảng Markdown, các khóa làm cột tiêu đề, một hàng cho mỗi bản ghi. Hai trăm đối tượng chứa 3.000 dòng JSON thô được thu gọn lại 200 hàng bảng.
Việc tiết kiệm không phải là mỹ phẩm. Trong JSON thô, mỗi bản ghi trong số 200 bản ghi đó lặp lại tên trường
"created_at", tên trường "customer_id", vân vân. Trong một bảng, mỗi
tên xuất hiện đúng một lần ở hàng tiêu đề. Đối với LLM hoạt động theo giới hạn ngữ cảnh, đó là
sự khác biệt giữa một tập dữ liệu phù hợp và không phù hợp. Bộ đếm mã thông báo bên dưới đầu ra tạo ra
cụ thể này - chuyển đổi cùng một tệp theo cả hai cách và xem số lượng giảm xuống.
Nơi nó xuống cấp: hồ sơ rách rưới. Nếu một nửa đối tượng của bạn có address
chặn còn các trường khác thì không, hoặc nếu một trường bản thân nó là một đối tượng lồng nhau thì một bảng phẳng không thể biểu diễn
sạch sẽ đó. Bạn sẽ có một bảng rộng hơn với các khoảng trống hoặc nội dung lồng nhau được đưa vào phần riêng của nó.
Nếu dữ liệu của bạn thực sự ở dạng bảng, trước tiên hãy xuất dữ liệu đó dưới dạng CSV và sử dụng
Công cụ chuyển đổi CSV sang Markdown
thường sẽ cung cấp các bảng gọn gàng hơn vì ngay từ đầu CSV không thể bị rách nát.
Khi nào bạn không nên chuyển đổi chút nào
Cần phải nói thẳng về điều này, vì nhiều trang bán công cụ chuyển đổi sẽ không: LLM có thể đọc JSON thô một cách hoàn hảo. Đó là một định dạng mà các mô hình đã sử dụng rất nhiều trong quá trình đào tạo. Bạn không cần phải chuyển đổi bất cứ điều gì.
Giữ JSON thô khi các khóa chính xác quan trọng. Nếu bạn yêu cầu một người mẫu viết mã dựa trên phản hồi API - giao diện TypeScript, trình phân tích cú pháp, chức năng ánh xạ - nó cần tên khóa theo nghĩa đen, cách lồng chữ và kiểu chữ. Markdown làm mờ một số nội dung đó mục đích. Dán tải trọng thô hoặc một mẫu đã được cắt bớt của nó và để mô hình xem nó sẽ như thế nào thực sự đang phân tích cú pháp.
Chuyển đổi khi có con người tham gia hoặc khi mã thông báo bị hạn chế. bạn muốn hiểu những gì một API lạ trả về. Bạn đang xem lại tệp cấu hình mà người khác đã viết. bạn là đưa một bản xuất lớn vào mô hình và tệp thô có 40% dấu câu. Đó là những trường hợp một Trình chuyển đổi JSON sang Markdown kiếm được vị trí của nó. Mọi thứ khác là hương vị.
Tệp được rút gọn, tệp được in đẹp và dòng JSON
Ba biến thể xuất hiện liên tục và chúng hoạt động khác nhau:
- JSON được rút gọn - một dòng rất lớn, không có khoảng trắng. Đó là định dạng của hầu hết các API thực sự trở lại. Con người không thể đọc được và người mẫu cũng khó đọc vì không có dòng nghỉ để neo vào. Ở đây việc chuyển đổi giúp ích nhiều nhất; bạn đi từ một dòng 200 KB đến một tài liệu có cấu trúc.
- JSON được in đẹp - đã thụt lề rồi. Dễ đọc hơn, nhưng thụt lề bản thân hiện tại có hàng nghìn không gian hàng đầu mà bạn đang trả tiền cho các mã thông báo. Markdown mang lại cho bạn hệ thống phân cấp mà không có hóa đơn khoảng trắng.
- Dòng NDJSON/JSON - một đối tượng JSON hoàn chỉnh trên mỗi dòng, không có mảng gói.
Tiêu chuẩn cho nhật ký và xuất phát trực tuyến. Bản chất nó đồng nhất, khiến nó gần với lý tưởng
cho đầu ra bảng. Nếu tập tin của bạn là
.jsonlhoặc.ndjson, đổi tên nó thành.jsonhoặc ngắt dòng trong một mảng trước khi tải lên.
Một cảnh báo thực tế: tệp không đúng định dạng sẽ không chuyển đổi được. Dấu phẩy ở cuối, dấu ngoặc đơn thay vì
gấp đôi, dòng mới không thoát bên trong chuỗi hoặc đi lạc NaN từ một bản xuất Python sẽ tất cả
xác nhận thất bại. Trước tiên hãy chạy tệp qua kẻ nói dối nếu nó đến từ nơi nào đó bất thường.
Nơi này được sử dụng
- Hiểu API không có giấy tờ. Ghi lại một phản hồi thực sự, chuyển đổi nó và bạn đã có bản phác thảo dễ đọc về hình dạng phản hồi — tốt hơn hầu hết tài liệu của nhà cung cấp và bạn có thể đưa nó cho một mô hình để tham khảo.
- Xem xét phân tích hoặc xuất kết xuất. Vài nghìn sự kiện từ một sản phẩm công cụ phân tích trở thành một bảng mà bạn thực sự có thể đặt câu hỏi.
- Cấu hình kiểm tra Tệp kê khai Kubernetes, cấu hình ESLint, cài đặt triển khai — được chuyển đổi thành Markdown, tính kế thừa và phần ghi đè trở nên rõ ràng theo cách chúng không có dấu ngoặc nhọn lồng nhau.
- Viết tài liệu. Đầu ra Markdown rơi thẳng vào README, wiki trang hoặc trang tài liệu mà không cần định dạng lại.
- So sánh hai tải trọng. Chuyển đổi trước và sau, khác biệt Markdown. Kết cấu những thay đổi nổi bật hơn nhiều so với những thay đổi trong JSON chứa đầy dấu ngoặc được di chuyển.
Nếu JSON tồn tại trong Codebase, hãy chuyển đổi Codebase
Hầu hết các tệp JSON không độc lập. Họ là một package.json, một tập tin cố định, một hạt giống
tập dữ liệu, thông số OpenAPI - nằm bên trong kho lưu trữ bên cạnh mã đọc chúng. Chuyển đổi
một tệp riêng biệt đó cung cấp cho mô hình dữ liệu nhưng không có ngữ cảnh.
Khi rơi vào tình huống đó, hãy sử dụng Kho lưu trữ GitHub sang trình chuyển đổi văn bản thay vào đó, hoặc thư mục cục bộ bộ chuyển đổi nếu dự án nằm trên máy của bạn và không được đẩy đi đâu cả. Đánh dấu vào các tệp JSON cộng các tệp nguồn sử dụng chúng và bạn nhận được một đốm văn bản chứa cả hai mặt của mối quan hệ. Có một GitLab phiên bản quá. Đây gần như luôn là động thái tốt hơn cho bất kỳ điều gì liên quan đến phát triển - trình chuyển đổi một tệp dành cho JSON tự xuất hiện.
Câu hỏi thường gặp
Làm cách nào để chuyển đổi JSON thành Markdown?
Tải lên .json ở trên và nó trở lại dưới dạng Markdown - các đối tượng được lồng nhau dưới dạng cấp độ tiêu đề, mảng bản ghi thống nhất dưới dạng bảng ống và khóa dưới dạng trường được gắn nhãn. Miễn phí, 50 MB mỗi tệp, không cần tài khoản. Tải xuống dưới dạng .md hoặc sao chép nó vào một tài liệu, một vấn đề hoặc một lời nhắc.
Mảng đối tượng có trở thành một bảng không?
Khi các đối tượng có chung một hình dạng, đúng vậy - đó là trường hợp Markdown xử lý tốt nhất. Danh sách các bản ghi có cùng khóa sẽ chuyển đổi thành bảng ống với một cột cho mỗi khóa, dễ quét hơn nhiều so với mảng thô. Các mảng không đồng nhất, trong đó mỗi phần tử có các trường khác nhau, thay vào đó sẽ quay trở lại các phần vì không có cột nhất quán nào được đặt để xây dựng.
Nó xử lý việc làm tổ sâu như thế nào?
Lồng bản đồ vào độ sâu tiêu đề và Markdown hết lúc ######. Một tệp cấu hình được lồng sâu tám cấp sẽ chạm đáy và các lớp sâu nhất sẽ san bằng cấp trên. Đối với các kết cấu có độ sâu văn bản thuần túy cũng không tệ hơn - không có thứ gì có thể đọc được sẽ tồn tại được.
Điều này có tốt cho việc ghi lại phản hồi API không?
Đó là một cách nhanh chóng để đưa tải trọng thực sự vào trang tài liệu hoặc yêu cầu kéo mà không cần định dạng thủ công. Dán một phản hồi mẫu, chuyển đổi và bạn có một bảng gồm các trường hiển thị ở bất kỳ nơi nào Markdown hiển thị. Điều nó không thể suy ra là trường nào là tùy chọn hoặc ý nghĩa của loại đó khi một giá trị xảy ra. null trong mẫu của bạn.
JSON tới Markdown hoặc JSON thành văn bản cho LLM?
Markdown nếu hình dạng mang ý nghĩa — bạn muốn mô hình hiểu rằng các trường này thuộc về đối tượng đó. Nhắn tin nếu bạn đang phân chia các phần nhúng, trong đó các ký tự cú pháp bị nhiễu làm loãng vectơ. Đối với một tải trọng duy nhất mà bạn muốn được giải thích, Markdown đọc tốt hơn và chi phí chỉ cao hơn một chút.
Markdown hoặc Văn bản thuần túy và những gì khác ở đây
Nếu bạn không muốn bất kỳ cấu trúc nào cả - bạn đang xây dựng các phần nhúng, lập chỉ mục cho tìm kiếm hoặc nén một tập tin xuống số lượng mã thông báo nhỏ nhất có thể - hãy lấy JSON thành văn bản thuần túy tuyến đường thay vào đó. Nó loại bỏ hoàn toàn cú pháp thay vì dịch nó. Chuyển đổi định dạng ở đầu trang này chuyển đổi giữa hai trang và đưa tệp bạn đã chọn đi qua, vì vậy bạn có thể thử cả hai mà không cần tải lên hai lần.
Đối với các định dạng có cấu trúc khác, XML tới Markdown xử lý các nguồn cấp dữ liệu, tải trọng SOAP và lược đồ doanh nghiệp, đồng thời HTML tới Markdown tay cầm các trang web đã lưu. File2Txt là điểm truy cập chung nếu bạn không muốn chọn một trang — nó chứa các tệp PDF, tệp Office, hình ảnh và tài liệu lưu trữ là tốt. Có một bài viết dài hơn trên chuẩn bị tập tin cho LLM nếu bạn muốn tranh luận rộng hơn.
Repo2Txt được xây dựng và duy trì bởi v12hero, một nhà phát triển độc lập xây dựng các ứng dụng web và ứng dụng gốc ưu tiên quyền riêng tư.