Details
-
Improvement
-
Resolution: Unresolved
-
Minor
-
None
-
None
-
None
-
3
-
9223372036854775807
Description
Since we have a DGX sitting mostly unused (gpu-wise), I thought it would be an interesting idea to run it on various documentation we have to highlight problems. This resulted in various useful actionable data and Andreas suggested to do the same on the Lustre manual.
This also seems to have returned useful data, I am going to post the structured results here hoping somebody could take a look and push patches as needed.
Do not take the suggestions as gospel, but in general it highlights somewhat problematic areas and even if you use a different way to fix it - that's still beneficial. In particular suggestions like "use file system or filesystem consistently" are good, but unlike what the model proposes, we actually want to use filesystem as a single word.
The results from my manpage runs suffered from some hallucinations including some not really there spelling mistakes, so don't be surprised if you encounter something like this, but this is a much larger model result, so should be better at not doing this. In fact I did some spotchecking and it looks like all spelling errors below for the most part are not there, may be the prompt needs to be improved to say that it's ok for there not to be any spelling errors?
This is the prompt I used (model llama 3.1 405b quantified to 4 bits from 16 so it actually fits):
prompt = """You are an expert proofreader and your job is to review Lustre filesystem documentation.
Read the below section in XML format for spelling and grammar errors, inconsistencies and poor wording:
```
%s
```Proofread the above document and provide your feedback.
Be specific and short, recommend suggested fixes for misspellings and grammar errors.
Limit every suggestion to 50 words or less.
Explain inconsistencies.
Respond using JSON like this:
{"spelling":[{"original":..., "fix":...}],"grammar":[{"original":...,"fix":...}],"inconsistency":[{"original":...,"explanation":...}],"wording":[{"original":...,"suggestion":...}]}
"""
As you can see, the results are JSON split into different categories, hopefully even if you don't know what json is too deeply, the data is useful.
Attachments
Activity
I am adding archives with two more LLMs results on the same ludoc codebase with teh same prompt as results are different (And even tend to be different from run to run)
ZFSSnapshots.xml
{
"spelling": [
{
"original": "zfssnapshotsReq",
"fix": "zfsSnapshotsReq"
},
{
"original": " foreign/- ",
"fix": "foreign -"
},
{
"original": " curently",
"fix": "currently"
}
],
"grammar": [
{
"original": "the snapshot and file system may share a single copy of the data until a file is changed on the file system.",
"fix": "The snapshot and file system may share a single copy of the data until a file is changed on the file system."
},
{
"original": " Snapshots are non-atomic across multiple MDTs and OSTs, which means that if there is activity on the file system while a snapshot is being taken, there may be user-visible namespace inconsistencies with files created or destroyed in the interval between the MDT and OST snapshots.",
"fix": "Snapshots are non-atomic across multiple MDTs and OSTs. This means that if there is activity on the file system while a snapshot is being taken, user-visible namespace inconsistencies may occur due to files being created or destroyed between MDT and OST snapshots."
}
],
"inconsistency": [
{
"original": "The feature is enabled by default and cannot be disabled.",
"explanation": "This statement seems inconsistent with the rest of the document, which provides instructions on how to create and manage snapshots. It would be clearer to specify under what conditions the feature cannot be disabled."
}
],
"wording": [
{
"original": "Filesystem snapshots are intended to be mounted on user-accessible nodes, such as login nodes, so that users can restore files (e.g. after accidental delete or overwrite) without administrator intervention.",
"suggestion": "Consider rephrasing for better readability: 'File system snapshots are designed to be mounted on accessible nodes, like login nodes, allowing users to recover files without administrative assistance.'"
},
{
"original": "Only files that are currently being modified by clients (write, create, unlink) may be inconsistent as noted above if the barrier is not used.",
"suggestion": "Rephrase for clarity: 'Files being actively modified by clients through write, create, or unlink operations may become inconsistent without a barrier.'"
}
]
}
V_LustreTroubleshooting.xml
{
"spelling": [],
"grammar": [
{
"original": "You will find information in this section about:",
"fix": "This section provides information on:"
}
],
"inconsistency": [
{
"original": "Part V",
"explanation": "The XML file does not specify a part number (e.g., Part I, Part II, etc.) for the included chapters. It is unclear how 'Part V' relates to the overall document structure."
},
{
"original": "xmlns:xl",
"explanation": "The namespace prefix 'xl' is declared but not used in the provided XML snippet."
}
],
"wording": [
{
"original": "Troubleshooting a Lustre File System",
"suggestion": "Consider adding a brief description or subtitle to provide context for the troubleshooting section."
},
{
"original": "<para><link linkend=\"lustretroubleshooting\" endterm=\"lustretroubleshooting.title\"/></para>",
"suggestion": "Instead of using an empty paragraph with a link, consider adding a brief description or title for each list item to improve readability."
}
]
}
VI_Reference.xml
{
"spelling": [],
"grammar": [
{
"original": "Part VI includes reference information about Lustre file system user utilities, configuration files and module parameters, programming interfaces, system configuration utilities, and system limits.",
"fix": "Part VI provides reference information on Lustre file system user utilities, configuration files and module parameters, programming interfaces, system configuration utilities, and system limits."
},
{
"original": "You will find information in this section about:",
"fix": "This section covers the following topics:"
}
],
"inconsistency": [
{
"original": "xmlns:xl='http://www.w3.org/1999/xlink' version='5.0' xml:lang='en-US'",
"explanation": "The namespace prefix 'xl' is not used anywhere in the document. Consider removing it."
},
{
"original": "href='LustreRecovery.xml' xmlns:xi='http://www.w3.org/2001/XInclude'",
"explanation": "The namespace declaration for 'xi' should be included only once, at the top of the document."
}
],
"wording": [
{
"original": "user utilities",
"suggestion": "Consider using a more descriptive phrase, such as 'command-line tools' or 'end-user utilities'."
},
{
"original": "system limits",
"suggestion": "Consider adding more context or clarification on what system limits refer to in the context of Lustre file systems."
}
]
}
UserUtilities.xml
{
"spelling": [
{
"original": "maintainance",
"fix": "maintenance"
}
],
"grammar": [
{
"original": "If a timeout occurs, a message (similar to this one), appears on the console of the client, and in /var/log/messages:",
"fix": "If a timeout occurs, a message similar to this one appears on the console of the client and in /var/log/messages:"
},
{
"original": "When mounting a Lustre file system, mount(8) executes the /sbin/mount.lustre command to complete the mount.",
"fix": "Mounting a Lustre file system involves executing the /sbin/mount.lustre command via mount(8)."
}
],
"inconsistency": [
{
"original": "The default mode is faster than the verbose/extent mode since it only counts the number of extents. The default mode is faster than the verbose/extent mode.",
"explanation": "These two sentences are redundant and can be condensed into one."
}
],
"wording": [
{
"original": "Note that as long as a file has extent lengths of tens of megabytes or more (i.e. read_bandwidth * seek_time > extent_length), the read performance for the file will not be significantly impacted by fragmentation, since file readahead can fully utilize the disk disk bandwidth even with occasional seeks.",
"suggestion": "Consider rephrasing this sentence to improve readability."
}
]
}
UpgradingLustre.xml
{
"spelling": [
{
"original": "be be",
"fix": "be"
},
{
"original": "xl:href",
"fix": "xlink:href"
}
],
"grammar": [
{
"original": "All servers must be upgraded at the same time, while some or all clients may be upgraded.",
"fix": "All servers must be upgraded at the same time; however, some or all clients may be upgraded independently."
},
{
"original": "The procedure for upgrading from a Lustre software release 2.x to a more recent 2.y major release of the Lustre software is described in this section.",
"fix": "This section describes the procedure for upgrading from a Lustre software release 2.x to a more recent 2.y major release."
},
{
"original": "To upgrade an existing 2.x installation to a more recent major release, complete the following steps:",
"fix": "Complete the following steps to upgrade an existing 2.x installation to a more recent major release:"
},
{
"original": "Before installing the Lustre software, back up ALL data.",
"fix": "Back up all data before installing the Lustre software."
},
{
"original": "The version of the kernel running on a Lustre client must be the same as the version of the lustre-client-modules-ver package being installed.",
"fix": "Ensure that the version of the kernel running on a Lustre client matches the version of the lustre-client-modules-ver package being installed."
}
],
"inconsistency": [
{
"original": "The document uses both 'Lustre software release 2.x' and 'Lustre release 2.x'.",
"explanation": "Use consistent terminology throughout the document."
},
{
"original": "Some sections use an ordered list with letters (a, b, c), while others use numbers.",
"explanation": "Maintain a consistent numbering style throughout the document."
}
],
"wording": [
{
"original": "This chapter describes interoperability between Lustre software releases.",
"suggestion": "Consider rephrasing to 'This chapter explains how different Lustre software releases work together.'"
},
{
"original": "The DNE feature allows using multiple MDTs within a single filesystem namespace, and each MDT can each serve one or more remote sub-directories in the file system.",
"suggestion": "Break up this long sentence for better readability."
},
{
"original": "For more information about wide striping, see .",
"suggestion": "Consider providing a brief explanation of wide striping before referencing external sources."
}
]
}
UnderstandingLustre.xml
{
"spelling": [],
"grammar": [
{
"original": "allows Lustre to leverage the scalability and data integrity features of ZFS for individual storage targets.",
"fix": "allows Lustre to leverage the scalability and data integrity features of ZFS for individual storage targets;"
}
],
"inconsistency": [
{
"original": "The maximum file size is not limited by the size of a single target. In a Lustre file system, files can be striped across multiple objects (up to 2000), and each object can be up to 16 TiB in size with ldiskfs, or up to 256PiB with ZFS.",
"explanation": "The text mentions two different maximum file sizes: 31.25 PiB for ldiskfs and 8EiB for ZFS, but then states the maximum file size is limited only by available space on OSTs, which could be confusing."
}
],
"wording": [
{
"original": "No space is reserved on the OST for unwritten data.",
"suggestion": "Consider rephrasing to 'No space is allocated on the OST for unwritten data' for clarity."
}
]
}
UnderstandingLustreNetworking.xml
{
"spelling": [],
"grammar": [
{
"original": "the network communication infrastructure required by the Lustre file system is implemented using the Lustre networking (LNet) feature.",
"fix": "The network communication infrastructure required by the Lustre file system is implemented as the Lustre Networking (LNet) feature."
},
{
"original": "Remote direct memory access (RDMA) is permitted when supported by underlying networks using the appropriate Lustre network driver (LND).",
"fix": "Remote direct memory access (RDMA) is allowed when supported by underlying networks using the corresponding Lustre Network Driver (LND)."
}
],
"inconsistency": [
{
"original": "LNet permits end-to-end read/write throughput at or near peak bandwidth rates on a variety of network interconnects.",
"explanation": "This sentence seems to be inconsistent with the rest of the document, which is formal and descriptive. This sentence appears more like a marketing claim."
}
],
"wording": [
{
"original": "In certain circumstances it might be desirable for Lustre file system traffic to pass between multiple LNets.",
"suggestion": "In some cases, you may want Lustre file system traffic to span multiple LNets."
},
{
"original": "LNet layer is connectionless, asynchronous and does not verify that data has been transmitted while the LND layer is connection oriented and typically does verify data transmission.",
"suggestion": "The LNet layer is connectionless and asynchronous, and it does not verify data transmission. In contrast, the LND layer is connection-oriented and typically verifies data transmission."
}
]
}
UnderstandingFailover.xml
{
"spelling": [
{
"original": "indication provided by the Lustre software",
"fix": "indications provided by the Lustre software"
},
{
"original": "RAID 5 or, preferably, RAID 6 storage.",
"fix": "RAID 5 or, preferably, RAID 6 storage;"
}
],
"grammar": [
{
"original": "In a high-availability (HA) system, unscheduled downtime is minimized by using redundant hardware and software components and software components",
"fix": "In a high-availability (HA) system, unscheduled downtime is minimized by using redundant hardware and software components."
},
{
"original": "the HA software must be able to completely power off the failed server or disconnect it from the shared storage device.",
"fix": "The HA software must be able to completely power off the failed server or disconnect it from the shared storage device."
}
],
"inconsistency": [
{
"original": "The Lustre software does not provide redundancy for data; it depends exclusively on redundancy of backing storage devices.",
"explanation": "This statement seems inconsistent with the rest of the document, which discusses failover configurations and redundancy. Consider clarifying or rephrasing this sentence."
},
{
"original": "OST failover functionality does not protect against corruption caused by a disk failure.",
"explanation": "This statement appears to contradict earlier statements about OST failover. It would be helpful to provide more context or clarify the limitations of OST failover."
}
],
"wording": [
{
"original": "Availability is accomplished by replicating hardware and/or software",
"suggestion": "Consider rephrasing to 'High availability is achieved through hardware and/or software replication' for better clarity."
},
{
"original": "the same physical logical unit number (LUN) should be visible from both servers.",
"suggestion": "Consider rephrasing to 'both servers must have access to the same LUN' for simplicity."
}
]
}
Ellis
I thought this would be timely for you to review
Peter