{"id":22908716,"url":"https://github.com/jayzhang42/federatedgpt-shepherd","last_synced_at":"2025-04-13T09:37:32.714Z","repository":{"id":158144891,"uuid":"633840778","full_name":"JayZhang42/FederatedGPT-Shepherd","owner":"JayZhang42","description":"Shepherd: A foundational framework enabling federated instruction tuning for large language models","archived":false,"fork":false,"pushed_at":"2023-07-07T13:13:46.000Z","size":7479,"stargazers_count":227,"open_issues_count":11,"forks_count":37,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-27T01:10:02.629Z","etag":null,"topics":["federated-learning","large-language-model"],"latest_commit_sha":null,"homepage":"https://arxiv.org/pdf/2305.05644.pdf","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JayZhang42.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-28T12:02:39.000Z","updated_at":"2025-03-23T03:20:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"dfe1ad73-168f-464a-bfc3-339594bab7d7","html_url":"https://github.com/JayZhang42/FederatedGPT-Shepherd","commit_stats":{"total_commits":14,"total_committers":1,"mean_commits":14.0,"dds":0.0,"last_synced_commit":"bcffa00e9642990ecc6210363a7f0dab91bef4dc"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JayZhang42%2FFederatedGPT-Shepherd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JayZhang42%2FFederatedGPT-Shepherd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JayZhang42%2FFederatedGPT-Shepherd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JayZhang42%2FFederatedGPT-Shepherd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JayZhang42","download_url":"https://codeload.github.com/JayZhang42/FederatedGPT-Shepherd/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248691632,"owners_count":21146408,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["federated-learning","large-language-model"],"created_at":"2024-12-14T03:30:35.135Z","updated_at":"2025-04-13T09:37:32.685Z","avatar_url":"https://github.com/JayZhang42.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"assets/shepherd\u0026llamas.png\" width=\"75%\"\u003e\n  \u003cbr\u003e\n  Shepherd\n  \u003cbr\u003e\n\u003c/h1\u003e\n\u003ch4 align=\"center\"\u003e\u003cem\u003e\u003cspan style=\"font-size:18pt\"\u003e A Platform Supporting Federated Instruction Tuning \u003c/span\u003e\u003c/em\u003e\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#Overview\"\u003eOverview\u003c/a\u003e •\n  \u003ca href=\"https://arxiv.org/pdf/2305.05644.pdf\"\u003ePaper\u003c/a\u003e •\n  \u003ca href=\"#Installation\"\u003eInstallation\u003c/a\u003e •\n  \u003ca href=\"#Data_Preparation\"\u003eData_Preparation\u003c/a\u003e •\n  \u003ca href=\"#Federated_Finetuning\"\u003eFederated_Finetuning\u003c/a\u003e •\n  \u003ca href=\"#Inference\"\u003eInference\u003c/a\u003e •\n  \u003ca href=\"#Citation\"\u003eCitation\u003c/a\u003e \n\u003c/p\u003e\n\n\n[![Code License: Apache 2.0](https://img.shields.io/badge/Code%20License-%20Apache%202.0-blue)](https://github.com/JayZhang42/FederatedGPT-Shepherd/blob/main/LICENSE) \\\n**Usage and License Notices**:The data, code and checkpoints are intended and licensed for research use only.\n\n## Overview\n\nRecent advancements in fine-tuning large language models (LLMs) have leveraged instructions created by humans or APIs (such as ChatGPT and GPT-4) to revolutionize NLP research and industry applications. However, the collection of instructions from a wide array of individuals presents challenges in cost and privacy. For instance, collecting vast amounts of daily conversations from users is a valuable means of providing guidance for LLMs, enabling them to generate authentic and genuine responses. However, privacy concerns may hinder users from sharing their conversations, resulting in a limited quantity of instructions that are not fully representative of the target population. Federated Learning, a well-studied and well-developed learning approach, provides a solution to addresses these challenges and paves the way for designing personalized LLMs tailored to individual users.\n\nThis repository, *Shepherd*, offers a foundational framework for exploring federated finetuning of LLMs using heterogeneous instructions across diverse categories. The framework is designed for ease of use, adaptability, and scalability to accommodate large datasets. Additionally, it facilitates seamless integration of novel algorithms and configurations, making it a convenient tool for researchers and practitioners in both the FL and the NLP community.\n\n## Paper\n\nWe are pleased to share our [***FedIT***](https://arxiv.org/pdf/2305.05644.pdf) [Paper], \"*Towards Building the Federated GPT: Federated Instruction Tuning.*\" We kindly invite you to read the paper for an in-depth understanding of Federated Instruction Tuning for LLMs and further insights into our repository.\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/FedIT.png\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n## Installation \n\nThe code requires some dependencies (Python=3.8)  as specified in `requirements.txt`. Please follow the relevant libraries to install or run:\n```bash\npip install -r requirements.txt\n```\nIf `bitsandbytes` doesn't work, [install it from source](https://github.com/TimDettmers/bitsandbytes/blob/main/compile_from_source.md). Windows users can follow [these instructions](https://github.com/tloen/alpaca-lora/issues/17).\n\n\n## Data_Preparation\n\nPrior to commencing the federated fine-tuning, make sure to create a data file for each individual client.\n```bash\nnum_client=10 # The number of clients\ndiff_quantity=0 # Whether clients have different amounts of data\npython client_data_allocation.py $num_client $diff_quantity\n```\nRunning this command will save the data files in the folder `./data/str(num_client)`. The data file `new-databricks-dolly-15k.json` for generating each client's local dataset is the first version of `databricks-dolly-15k` , which is a corpus of more than 15,000 records with 8 categeries generated by thousands of [Databricks Lab](https://www.databricks.com/learn/labs) employees. Please refer to their official repository [dolly](https://github.com/databrickslabs/dolly) for the latest version of data.\n\n### Categories distribution and Heteogeneity\nThe first version of `databricks-dolly-15k` contains 8 Categories, with the distribution of each category shown in the following subfigure provided on the right.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/twodonuts.png\" width=\"150%\"\u003e\n\u003c/p\u003e\n\nWithout federated learning, the model can be trained on only the particular local instruction categories of each user (left) due to privacy or cost issue. By implementing our Federated instruction tuning ([***FedIT***](https://arxiv.org/pdf/2305.05644.pdf)) framework with this repo *Shepherd*, the LLM can be trained on the local instruction datasets of all clients with greater diversity and quantity of data points that cover the entire range of the subject matter (right).\n\nThe following figure presents an illustrative depiction of the category distributions among each client, serving to exemplify the heterogeneity nature of clients' instructions.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/hetero.png\" width=\"150%\"\u003e\n\u003c/p\u003e\n\n### Use your own data\n\nYou can simply modify `client_data_allocation.py` to load your own  dataset for federated training.\n\n\n## Federated_Finetuning\n\nTo fully leverage the computational resources of each participating client, our lightweight Federated Learning framework employs the well-established parameter-efficient method, [LoRA](https://github.com/microsoft/LoRA), for conducting local training. The local training process is built upon the implementations of Hugging Face's [PEFT](https://github.com/huggingface/peft), Tim Dettmers' [bitsandbytes](https://github.com/TimDettmers/bitsandbytes), and the [Alpaca-lora](https://github.com/tloen/alpaca-lora), enabling the training to be completed within hours on a single NVIDIA TITAN RTX.\n\nExample usage:\n```bash\npython main.py --global_model 'chavinlo/alpaca-native'\\\n      --data_path  \"./data\" \\\n      --output_dir  './lora-shepherd-7b/'\\\n      --num_communication_rounds 10 \\\n      --num_clients  10 \\\n      --train_on_inputs \\\n      --group_by_length\n```\nWithin the `main.py` file, the GeneralClient is a Python class serves as a representation of the local client and encompasses five distinct sections that facilitate local training: \"prepare_local_dataset,\" \"build_local_trainer,\" \"initiate_local_training,\" \"train,\" and \"terminate_local_training.\" Each of these sections is easy to comprehend and can be easily customized by adding your own functions to meet specific requirements.\n\nWe can also tweak the hyperparameters:\n```bash\npython main.py --global_model 'chavinlo/alpaca-native'\\\n      --data_path  \"./data\" \\\n      --output_dir  './lora-shepherd-7b/'\\\n      --num_communication_rounds 10 \\\n      --num_clients  10 \\\n      --client_selection_frac 0.1 \\\n      --local_num_epochs  2 \\\n      --local_batch_size  64 \\\n      --local_micro_batch_size 32 \\\n      --local_learning_rate 0.0003 \\\n      --lora_r 8 \\\n      --lora_target_modules='[q_proj,k_proj,v_proj,o_proj]' \\\n      --train_on_inputs \\\n      --group_by_length\n```\n\nOur framework supports numerous popular LLMs, such as [LLaMA](https://github.com/facebookresearch/llama), [Alpaca](https://github.com/tatsu-lab/stanford_alpaca), [Vicuna](https://vicuna.lmsys.org/), [Baize](https://github.com/project-baize/baize-chatbot), and others. We welcome any pull requests that adapt our code to support additional models or datasets.\n\n\n## Inference \n\nThe `GlobalModel_generate.py` file streamlines the inference process for the global model by utilizing a Gradio interface. This file loads the foundation model from the Hugging Face Model Hub and obtains the LoRA weights and configurations from the output directory.\n\n```bash\npython GlobalModel_generate.py \\\n      --load_8bit \\\n      --base_model 'chavinlo/alpaca-native' \\\n      --lora_weights_path /output/path/to/lora_weights  \\\n      --lora_config_path /output/path/to/lora_config   \n      \n```\n\n\n## Citation\n\nPlease cite our FedIT paper and this repo if you find our repository helpful for your research. Thank you!\n```\n@misc{zhang2023building,\n      title={Towards Building the Federated GPT: Federated Instruction Tuning}, \n      author={Jianyi Zhang and Saeed Vahidian and Martin Kuo and Chunyuan Li and Ruiyi Zhang and Guoyin Wang and Yiran Chen},\n      year={2023},\n      eprint={2305.05644},\n      archivePrefix={arXiv},\n      primaryClass={cs.CL}\n}\n```\n```\n@misc{Shepherdgithub,\n  author = {Jianyi Zhang and Martin Kuo and Ruiyi Zhang and Guoyin Wang and Saeed Vahidian and Yiran Chen},\n  title = {Shepherd: A Lightweight GitHub Platform Supporting Federated Instruction Tuning},\n  year = {2023},\n  publisher = {GitHub},\n  journal = {GitHub repository},\n  howpublished = {\\url{https://github.com/JayZhang42/FederatedGPT-Shepherd}},\n}\n```\n\n## Note!\n\nWe are constantly working to enhance this framework by resolving bugs and extending its functionality and simulation capabilities. We welcome pull requests that adapt our code to support additional research goals, such as benchmarking of models and datasets, algorithmic enhancements, and hardware simulation.\n\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjayzhang42%2Ffederatedgpt-shepherd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjayzhang42%2Ffederatedgpt-shepherd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjayzhang42%2Ffederatedgpt-shepherd/lists"}