diff options
Diffstat (limited to 'dev/patchbot/README')
| -rw-r--r-- | dev/patchbot/README | 395 |
1 files changed, 395 insertions, 0 deletions
diff --git a/dev/patchbot/README b/dev/patchbot/README new file mode 100644 index 0000000..a645cc3 --- /dev/null +++ b/dev/patchbot/README @@ -0,0 +1,395 @@ +Patchbot: AI bot making use of Natural Language Processing to suggest backports +=============================================================== 2023-12-18 ==== + + +Background +---------- + +Selecting patches to backport from the development branch is a tedious task, in +part due to the abundance of patches and the fact that many bug fixes are for +that same version and not for backporting. The more it gets delayed, the harder +it becomes, and the harder it is to start, the less likely it gets started. The +urban legend along which one "just" has to do that periodically doesn't work +because certain patches need to be left hanging for a while under observation, +others need to be merged urgently, and for some, the person in charge of the +backport might simply need an opinion from the patch's author or the affected +subsystem maintainer, and this cannot make the whole backport process stall. + +The information needed to figure if a patch needs to be backported is present +in the commit message, with varying nuances such as "may", "may not", "should", +"probably", "shouldn't unless", "keep under observation" etc. One particularly +that is specific to backports is that the opinion on a patch may change over +time, either because it was later found to be wrong or insufficient, or because +the former analysis mistakenly suggested to backport or not to. + +This means that the person in charge of the backports has to read the whole +commit message for each patch, to figure the backporting instructions, and this +takes a while. + +Several attempts were made over the years to try to partially automate this +task, including the cherry-pick mode of the "git-show-backports" utility that +eases navigation back-and-forth between commits. + +Lately, a lot of progress was made in the domain of Natural Language +Understanding (NLU) and more generally Natural Language Processing (NLP). Since +the first attempts in early 2023 involving successive layers of the Roberta +model, called from totally unreliable Python code, and December 2023, the +situation evolved from promising but unusable to mostly autonomous. + +For those interested in history, the first attempts in early 2023 involved +successive layers of the Roberta model, but these were relying on totally +unreliable Python code that broke all the time and could barely be transferred +to another machine without upgrading or downgrading the installed modules, and +it used to use huge amounts of resources for a somewhat disappointing result: +the verdicts were correct roughly 60-70% of the time, it was not possible to +get hints such as "wait" nor even "uncertain". It could just be qualified as +promising. Another big limitation was the limit to 256 tokens, forcing the +script to select only the last few lines of the commit message to take the +decision. Roughly at the same time, in March 2023 Meta issued their much larger +LLaMa model, and Georgi Gerganov released "llama.cpp", an open-source C++ +engine that loads and runs such large models without all the usual problems +inherent to the Python ecosystem. New attempts were made with LLaMa and it was +already much better than Roberta, but the output was difficult to parse, and it +required to be combined with the final decision layer of Roberta. Then new +variants of LLaMa appeared such as Alpaca, which follows instructions, but +tends to forget them if given before the patch, then Vicuna which was pretty +reliable but very slow at 33B size and difficult to tune, then Airoboros, +which was the first one to give very satisfying results in a reasonable time, +following instructions reasonably closely with a stable output, but with +sometimes surprising analysis and contradictions. It was already about 90% +reliable and considered as a time saver in 13B size. Other models were later +tried as they appeared such as OpenChat-3.5, Juna, OpenInstruct, Orca-2, +Mistral-0.1 and it variants Neural and OpenHermes-2.5. Mistral showed an +unrivaled understanding despite being smaller and much faster than other ones, +but was a bit freewheeling regarding instructions. Dolphin-2.1 rebased on top +of it gave extremely satisfying results, with less variations in the output +format, but still the script had difficulties trying to catch its conclusion +from time to time, though it was pretty much readable for the human in charge +of the task. And finally just before releasing, Mistral-0.2 was released and +addressed all issues, with a human-like understanding and perfectly obeying +instructions, providing an extremely stable output format that is easy to parse +from simple scripts. The decisions now match the human's ones in close to 100% +of the patches, unless the human is aware of extra context, of course. + + +Architecture +------------ + +The current solution relies on the llama.cpp engine, which is a simple, fast, +reliable and portable engine to load models and run inference, and the +Mistral-0.2 LLM. + +A collection of patches is built from the development branch since the -dev0 +tag, and for each of them, the engine is called to evaluate the developer's +intent based on the commit message. A detailed context explaining the haproxy +maintenance model and what the user wants is passed, then the LLM is invited to +provide its opinion on the need for a backport and an explanation of the reason +for its choice. This often helps the user to find a quick summary about the +patch. All these outputs are then converted to a long HTML page with colors and +radio buttons, where patches are pre-selected based on this classification, +that the user can consult and adjust, read the commits if needed, and the +selected patches finally provide some copy-pastable commands in a text-area to +select commit IDs to work on, typically in a form that's suitable for a simple +"git cherry-pick -sx". + +The scripts are designed to be able to run on a headless machine, called from a +crontab and with the output served from a static HTTP server. + +The code is currently found from Georgi Gerganov's repository: + + https://github.com/ggerganov/llama.cpp + +Tag b1505 is known to work fine, and uses the GGUF file format. + +The model(s) can be found on Hugging Face user "TheBloke"'s collection of +models: + + https://huggingface.co/TheBloke + +Model Mistral-7B-Instruct-v0.2-GGUF quantized at Q5K_M is known to work well +with the llama.cpp version above. + + +Deployment +---------- + +Note: it is a good idea to start to download the model(s) in the background as + such files are typically 5 GB or more and can take some time to download + depending on the internet bandwidth. + +It seems reasonable to create a dedicated user to periodically run this task. +Let's call it "patchbot". Developers should be able to easily run a shell from +this user to perform some maintenance or testing (e.g. "sudo"). + +All paths are specified in the example "update-3.0.sh" script, and assume a +deployment in the user's home, so this is what is being described here. The +proposed deployment layout is the following: + + $HOME (e.g. /home/patchbot) + | + +- data + | | + | +-- models # GGUF files from TheBloke's collection + | | + | +-- prompts # prompt*-pfx*, prompt*-sfx*, cache + | | + | +-- in + | | | + | | +-- haproxy # haproxy Git repo + | | | + | | +-- patches-3.0 # patches from development branch 3.0 + | | + | +-- out # report directory (HTML) + | + +- prog + | | + | +-- bin # program(s) + | | + | +-- scripts # processing scripts + | | + | +-- llama.cpp # llama Git repository + + +- Let's first create the structure: + + mkdir -p ~/data/{in,models,prompts} ~/prog/{bin,scripts} + +- data/in/haproxy must contain a clone of the haproxy development tree that + will periodically be pulled from: + + cd ~/data/in + git clone https://github.com/haproxy/haproxy + cd ~ + +- The prompt files are a copy of haproxy's "dev/patchbot/prompt/" subdirectory. + The prompt files are per-version because they contain references to the + haproxy development version number. For each prompt, there is a prefix + ("-pfx"), that is loaded before the patch, and a suffix ("-sfx") that + precises the user's expectations after reading the patch. For best efficiency + it's useful to place most of the explanation in the prefix and the least + possible in the suffix, because the prefix is cacheable. Different models + will use different instructions formats and different explanations, so it's + fine to keep a collection of prompts and use only one. Different instruction + formats are commonly used, "llama-2", "alpaca", "vicuna", "chatml" being + common. When experimenting with a new model, just copy-paste the closest one + and tune it for best results. Since we already cloned haproxy above, we'll + take the files from there: + + cp ~/data/in/haproxy/dev/patchbot/prompt/*txt ~/data/prompts/ + + Upon first run, a cache file will be produced in this directory by parsing + an empty file and saving the current model's context. The cache file will + automatically be deleted and rebuilt if it is absent or older than the prefix + or suffix file. The cache files are specific to a model so when experimenting + with other models, be sure not to reuse the same cache file, or in doubt, + just delete them. Rebuilding the cache file typically takes around 2 minutes + of processing on a 8-core machine. + +- The model(s) from TheBloke's Hugging Face account have to be downloaded in + GGUF file format, quantized at Q5K_M, and stored as-is into data/models/. + +- data/in/patches-3.0/ is where the "mk-patch-list.sh" script will emit the + patches corresponding to new commits in the development branch. Its suffix + must match the name of the current development branch for patches to be found + there. In addition, the classification of the patches will be emitted there + next to the input patches, with the same name as the original file with a + suffix indicating what model/prompt combination was used. + + mkdir -p ~/data/in/patches-3.0 + +- data/out is where the final report will be emitted. If running on a headless + machine, it is worth making sure that this directory is accessible from a + static web server. Thus either create a directory and place a symlink or + configuration somewhere in the web server's settings to reference this + location, or make it a symlink to another place already exported by the web + server and make sure the user has the permissions to write there. + + mkdir -p ~/data/out + + On Ubuntu-20.04 it was found that the package "micro-httpd" works out of the + box serving /var/www/html and follows symlinks. As such this is sufficient to + expose the reports: + + sudo ln -s ~patchbot/data/out /var/www/html/patchbot + +- prog/bin will contain the executable(s) needed to operate, namely "main" from + llama.cpp: + + mkdir -p ~/prog/bin + +- prog/llama.cpp is a clone of the "llama.cpp" GitHub repository. As of + december 2023, the project has improved its forward compatibility and it's + generally both safe and recommended to stay on the last version, hence to + just clone the master branch. In case of difficulties, tag b1505 was proven + to work well with the aforementioned model. Building is done by default for + the local platform, optimised for speed with native CPU. + + mkdir -p ~/prog + cd ~/prog + git clone https://github.com/ggerganov/llama.cpp + [ only in case of problems: cd llama.cpp && git checkout b1505 ] + + make -j$(nproc) main LLAMA_FAST=1 + cp main ~/prog/bin/ + cd ~ + +- prog/scripts needs the following scripts: + - mk-patch-list.sh from haproxy's scripts/ subdirectory + - submit-ai.sh, process-*.sh, post-ai.sh, update-*.sh + + cp ~/data/in/haproxy/scripts/mk-patch-list.sh ~/prog/scripts/ + cp ~/data/in/haproxy/dev/patchbot/scripts/*.sh ~/prog/scripts/ + + - verify that the various paths in update-3.0.sh match your choices, or + adjust them: + + vi ~/prog/scripts/update-3.0.sh + + - the tool is memory-bound, so a machine with more memory channels and/or + very fast memory will usually be faster than a higher CPU count with a + lower memory bandwidth. In addition, the performance is not linear with + the number of cores and experimentation shows that efficiency drops above + 8 threads. For this reason the script integrates a "PARALLEL_RUNS" variable + indicating how many instances to run in parallel, each on its own patch. + This allows to make better use of the CPUs and memory bandwidth. Setting + 2 instances for 8 cores / 16 threads gives optimal results on dual memory + channel systems. + +From this point, executing this update script manually should work and produce +the result. Count around 0.5-2 mn per patch on a 8-core machine, so it can be +reasonably fast during the early development stages (before -dev1) but +unbearably long later, where it can make more sense to run it at night. It +should not report any error and should only report the total execution time. + +If interrupted (Ctrl-C, logout, out of memory etc), check for incomplete .txt +files in ~/data/in/patches*/ that can result from this interruption, and delete +them because they will not be reproduced: + + ls -lart ~/data/in/patches-3.0/*.txt + ls -lS ~/data/in/patches-3.0/*.txt + +Once the output is produced, visit ~/data/out/ using a web browser and check +that the table loads correctly. Note that after a new release or a series of +backports, the table may appear empty, it's just because all known patches are +already backported and collapsed by default. Clicking on "All" at the top left +will unhide them. + +Finally when satisfied, place it in a crontab, for example, run every hour: + + crontab -e + + # m h dom mon dow command + # run every hour at minute 02 + 2 * * * * /home/patchbot/update-3.0.sh + + +Usage +----- + +Using the HTML output is a bit rustic but efficient. The interface is split in +5 columns from left to right: + + - first column: patch number from 1 to N, just to ease navigation. Below the + number appears a radio button which allows to mark this patch as the start + of the review. When clicked, all prior patches disappear and are not listed + anymore. This can be undone by clicking on the radio button under the "All" + word in this column's header. + + + - second column: commit ID (abbreviated "CID" in the header). It's a 8-digit + shortened representation of the commit ID. It's presented as a link, which, + if clicked, will directly show that commit from the haproxy public + repository. Below the commit ID is the patch's author date in condensed + format "DD-MmmYY", e.g. "18-Dec23" for "18th December 2023". It was found + that having a date indication sometimes helps differentiate certain related + patches. + + - third column: "Subject", this is the subject of the patch, prefixed with + the 4-digit number matching the file name in the directory (e.g. helps to + remove or reprocess one if needed). This is also a link to the same commit + in the haproxy's public repository. At the lower right under the subject + is the shortened e-mail address (only user@domain keeping only the first + part of the domain, e.g. "foo@haproxy"). Just like with the date, it helps + figuring what to expect after a recent discussion with a developer. + + - fourth column: "Verdict". This column contains 4 radio buttons prefiguring + the choice for this patch between "N" for "No", represented in gray (this + patch should not be backported, let's drop it), "U" for "Uncertain" in + green (still unsure about it, most likely the author should be contacted), + "W" for "Wait" in blue (this patch should be backported but not + immediately, only after it has spent some time in the development branch), + and "Y" for "Yes" in red (this patch must be backported, let's pick it). + The choice is preselected by the scripts above, and since these are radio + buttons, the user is free to change this selection. Reloading will lose the + user's choices. When changing a selection, the line's background changes to + match a similar color tone, allowing to visually spot preselected patches. + + - fifth column: reason for the choice. The scripts try to provide an + explanation for the choice of the preselection, and try to always end with + a conclusion among "yes", "no", "wait", "uncertain". The explanation + usually fits in 2-4 lines and is faster to read than a whole commit message + and very often pretty accurate. It's also been noticed that Mistral-v0.2 + shows much less hallucinations than others (it doesn't seem to invent + information that was not part of its input), so seeing certain topics being + discussed there generally indicate that they were in the original commit + message. The scripts try to emphasize the sensitive parts of the commit + message such as risks, dependencies, referenced issues, oldest version to + backport to, etc. Elements that look like issues numbers and commit IDs are + turned to links to ease navigation. + +In addition, in order to improve readability, the top of the table shows 4 +buttons allowing to show/hide each category. For example, when trying to focus +only on "uncertain" and "wait", it can make sense to hide "N" and "Y" and click +"Y" or "N" on the displayed ones until there is none anymore. + +In order to reduce the risk of missing a misqualified patch, those marked "BUG" +or "DOC" are displayed in bold even if tagged "No". It has been shown to be +sufficient to catch the eye when scrolling and encouraging to re-visit them. + +More importantly, the script will try to also check which patches were already +backported to the previous stable version. Those that were backported will have +the first two columns colored gray, and by default, the review will start from +the first patch after the last backported one. This explains why just after a +backport, the table may appear empty with only the footer "New" checked. + +Finally, at the bottom of the table is an editable, copy-pastable text area +that is redrawn at each click. It contains a series of 4 shell commands that +can be copy-pasted at once and assign commit IDs to 4 variables, one per +category. Most often only "y" will be of interest, so for example if the +review process ends with: + + cid_y=( 7dab3e82 456ba6e9 75f5977f 917f7c74 ) + +Then copy-pasting it in a terminal already in the haproxy-2.9 directory and +issuing: + + git cherry-pick -sx ${cid_y[@]} + +Will result in all these patches to be backported to that version. + + +Criticisms +---------- + +The interface is absolutely ugly but gets the job done. Proposals to revamp it +are welcome, provided that they do not alter usability and portability (e.g. +the ability to open the locally produced file without requiring access to an +external server). + + +Thanks +------ + +This utility is the proof that boringly repetitive tasks that can be offloaded +from humans can save their time to do more productive things. This work which +started with extremely limited tools was made possible thanks to Meta, for +opening their models after leaking it, Georgi Gerganov and the community that +developed around llama.cpp, for creating the first really open engine that +builds out of the box and just works, contrary to the previous crippled Python- +only ecosystem, Tom Jobbins (aka TheBloke) for making it so easy to discover +new models every day by simply quantizing all of them and making them available +from a single location, MistralAI for producing an exceptionally good model +that surpasses all others, is the first one to feel as smart and accurate as a +real human on such tasks, is fast, and totally free, and of course, HAProxy +Technologies for investing some time on this and for the available hardware +that permits a lot of experimentation. |