Skip to content

Commit 6dcbeb5

Browse files
Akash-NayakAkash-Nayak
committed
feat: Add documentation on data config selection
Signed-off-by: Akash-Nayak <akash19nayak@gmail.com>
1 parent c28a4ed commit 6dcbeb5

File tree

2 files changed

+201
-0
lines changed

2 files changed

+201
-0
lines changed

‎docs/data-config-selection.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Guidelines For Data Config Selection
2+
3+
This documentation outlines the recommended criteria and best practices for selecting the appropriate [data config](https://github.com/foundation-model-stack/fms-hf-tuning/blob/9ca5739a4f7c1f0c9446b28d1bb80939d4199a75/docs/advanced-data-preprocessing.md#data-config) based on the format and characteristics of the training data. Users can currently pass both YAML or JSON based configuration files as data_configs via `--data_config_path` flag.
4+
5+
## Scenarios tailored to different training data formats
6+
7+
![Guidelines for selecting data config](./images/data_config_guide.png)
8+
9+
Based on the structure of the training data, we have categorized it into three distinct scenarios, as illustrated in the hierarchical diagram above
10+
- Pre-training format (EPT data)
11+
- Question-Answer format
12+
- Chat-style format (single-turn or multi turn)
13+
14+
The supported data file formats are jsonl, json, arrow, and parquet.
15+
16+
### Data config for pre-training format data
17+
18+
If you want to perform Extended Pretraining (EPT) on your training data, then use the below data config. For EPT, set `packing` as `true` in the tuning config.
19+
20+
```yaml
21+
dataprocessor:
22+
type: default
23+
streaming: false
24+
datasets:
25+
# Commenting sampling ratio will concatenate the datasets
26+
- name: dataset_1
27+
# sampling: 1.0
28+
data_paths:
29+
- "tests/artifacts/jsonl/twitter_complaints_small.jsonl"
30+
# Either the below data_handlers section can be used or the dataset_text_field in the tuning config can be used for specifying the field in the dataset that contains the training text for EPT.
31+
# In this sample ept_data, "output" field contains the text for training. Please change it according to your data.
32+
# If your data is already tokenized data, then comment the data handlers section
33+
data_handlers:
34+
- name: tokenize
35+
arguments:
36+
remove_columns: all
37+
batched: false
38+
fn_kwargs:
39+
text_column_name: "output"
40+
max_length: 4096
41+
# If there are multiple datasets, add them in the data config as well.
42+
# - name: dataset_2
43+
# sampling: 1.0
44+
# data_paths:
45+
# - /path/to/the/dataset
46+
# data_handlers:
47+
# - name: tokenize
48+
# arguments:
49+
# remove_columns: all
50+
# batched: false
51+
# fn_kwargs:
52+
# text_column_name: "text"
53+
# max_length: 4096
54+
```
55+
56+
Example training data:
57+
58+
```json
59+
{"tweet_text":"@HMRCcustomers No this is my first job","id":0,"label":2,"text_label":"no complaint","output":"### Text: @HMRCcustomers No this is my first job\n\n### Label: no complaint"}
60+
61+
{"tweet_text":"@KristaMariePark Thank you for your interest! If you decide to cancel, you can call Customer Care at 1-800-NYTIMES.","id":1,"label":2,"text_label":"no complaint","output":"### Text: @KristaMariePark Thank you for your interest! If you decide to cancel, you can call Customer Care at 1-800-NYTIMES.\n\n### Label: no complaint"}
62+
```
63+
64+
The key or field containing the training data can be specified using the `dataset_text_field` parameter in the `tuning config`. Alternatively, it may be defined using the `text_column_name` field within the `fn_kwargs` section of `data_handlers`. However, these two methods should not be used simultaneously. For multiple datasets, the data_handlers approach should be used to define the appropriate field for each dataset individually.
65+
66+
It is recommended to perform EPT on a base model. If the `tokenizer_config.json` file contains the `chat_template` field, the model is likely instruction-tuned for chat or instruction-following tasks; otherwise, it is most likely a base model.
67+
68+
If the dataset consists of pre-tokenized data, the `data_handlers` section should be omitted, and the `dataset_text_field` should not be specified.
69+
70+
### Data config for question-answer format data
71+
72+
If the training data is in format of question-answer/instruction-response, then use the below data config.
73+
74+
```yaml
75+
dataprocessor:
76+
type: default
77+
streaming: false
78+
datasets:
79+
# If there are more than one dataset, then commenting the sampling ratio will concatenate the datasets.
80+
- name: dataset_1
81+
# sampling: 1.0
82+
data_paths:
83+
- "tests/artifacts/jsonl/twitter_complaints_small.jsonl"
84+
# If your data is already tokenized data, then comment the data handlers section
85+
data_handlers:
86+
- name: apply_custom_jinja_template
87+
arguments:
88+
remove_columns: all
89+
batched: false
90+
fn_kwargs:
91+
formatted_text_column_name: "formatted_chat_data"
92+
template: "{% raw %}### Input: {{tweet_text}} \\\n\\\n### Response: {{text_label}}{% endraw %}"
93+
# If there are multiple datasets, add them in the data config as well.
94+
```
95+
96+
Example training data:
97+
98+
```json
99+
{"tweet_text":"@HMRCcustomers No this is my first job","id":0,"label":2,"text_label":"no complaint"}
100+
101+
{"tweet_text":"@KristaMariePark Thank you for your interest! If you decide to cancel, you can call Customer Care at 1-800-NYTIMES.","id":1,"label":2,"text_label":"no complaint"}
102+
```
103+
104+
The template for formatting the data is specified in the `apply_custom_jinja_template`. In this case, the data formatting `template` is `{% raw %}### Input: {{tweet_text}} \\\n\\\n### Response: {{text_label}}{% endraw %}`, and the `response template` is defined as `\\\n### Response:`. These templates can be modified as needed to align with the structure of the training dataset. Additionally, the value of `dataset_text_field` in the tuning config should match the `formatted_text_column_name` specified in the `fn_kwargs` section of `data_handlers`.
105+
106+
If the dataset consists of pre-tokenized data, the `data_handlers` section should be omitted, and the `dataset_text_field` and `response_template` parameters should not be specified.
107+
108+
### Data config for chat-style format data
109+
110+
If the training data is in a single-turn/multi-turn chat format, then use the below data config.
111+
112+
```yaml
113+
dataprocessor:
114+
type: default
115+
streaming: false
116+
# This data config uses the chat template of the "ibm-granite/granite-3.1-8b-instruct" model for intruction-tuning of base model. If you want to modify the chat template you can edit the below chat template.
117+
# If your model is same instruct model then comment the chat template section.
118+
# If your model is a different instruct model (if the tokenizer_config.json file contains chat_template) other than "ibm-granite/granite-3.1-8b-instruct" model, then correct the below chat template with the model's chat template.
119+
chat_template: |
120+
{% raw %}
121+
{%- if messages[0]['role'] == 'system' %}
122+
{%- set system_message = messages[0]['content'] %}
123+
{%- set loop_messages = messages[1:] %}
124+
{%- else %}
125+
{%- set system_message = "Knowledge Cutoff Date: April 2024.\nToday's Date: " + strftime_now('%B %d, %Y') + ".\nYou are Granite, developed by IBM." %}
126+
{%- if tools and documents %}
127+
{%- set system_message = system_message + " You are a helpful AI assistant with access to the following tools. When a tool is required to answer the user's query, respond with <|tool_call|> followed by a JSON list of tools used. If a tool does not exist in the provided list of tools, notify the user that you do not have the ability to fulfill the request.\n\nWrite the response to the user's input by strictly aligning with the facts in the provided documents. If the information needed to answer the question is not available in the documents, inform the user that the question cannot be answered based on the available data." %}
128+
{%- elif tools %}
129+
{%- set system_message = system_message + " You are a helpful AI assistant with access to the following tools. When a tool is required to answer the user's query, respond with <|tool_call|> followed by a JSON list of tools used. If a tool does not exist in the provided list of tools, notify the user that you do not have the ability to fulfill the request." %}
130+
{%- elif documents %}
131+
{%- set system_message = system_message + " Write the response to the user's input by strictly aligning with the facts in the provided documents. If the information needed to answer the question is not available in the documents, inform the user that the question cannot be answered based on the available data." %}
132+
{%- else %}
133+
{%- set system_message = system_message + " You are a helpful AI assistant." %}
134+
{%- endif %}
135+
{%- if 'citations' in controls and documents %}
136+
{%- set system_message = system_message + '\n\nIn your response, use the symbols <co> and </co> to indicate when a fact comes from a document in the search result, e.g <co>0</co> for a fact from document 0. Afterwards, list all the citations with their corresponding documents in an ordered list.' %}
137+
{%- endif %}
138+
{%- if 'hallucinations' in controls and documents %}
139+
{%- set system_message = system_message + '\n\nFinally, after the response is written, include a numbered list of sentences from the response that are potentially hallucinated and not based in the documents.' %}
140+
{%- endif %}
141+
{%- set loop_messages = messages %}
142+
{%- endif %}
143+
{{- '<|start_of_role|>system<|end_of_role|>' + system_message + '<|end_of_text|>\n' }}
144+
{%- if tools %}
145+
{{- '<|start_of_role|>tools<|end_of_role|>' }}
146+
{{- tools | tojson(indent=4) }}
147+
{{- '<|end_of_text|>\n' }}
148+
{%- endif %}
149+
{%- if documents %}
150+
{{- '<|start_of_role|>documents<|end_of_role|>' }}
151+
{%- for document in documents %}
152+
{{- 'Document ' + loop.index0 | string + '\n' }}
153+
{{- document['text'] }}
154+
{%- if not loop.last %}
155+
{{- '\n\n'}}
156+
{%- endif%}
157+
{%- endfor %}
158+
{{- '<|end_of_text|>\n' }}
159+
{%- endif %}
160+
{%- for message in loop_messages %}
161+
{{- '<|start_of_role|>' + message['role'] + '<|end_of_role|>' + message['content'] + '<|end_of_text|>\n' }}
162+
{%- if loop.last and add_generation_prompt %}
163+
{{- '<|start_of_role|>assistant' }}
164+
{%- if controls %}
165+
{{- ' ' + controls | tojson()}}
166+
{%- endif %}
167+
{{- '<|end_of_role|>' }}
168+
{%- endif %}
169+
{%- endfor %}
170+
{% endraw %}
171+
datasets:
172+
# If there are more than one dataset, then commenting the sampling ratio will concatenate the datasets
173+
- name: dataset_1
174+
# sampling: 1.0
175+
data_paths:
176+
- "tests/artifacts/jsonl/multi_turn_chat_conversations.jsonl"
177+
# Comment the below data_handlers section if your data is already pre-tokenized data and contains the "input_ids", "labels", and "attention_mask".
178+
data_handlers:
179+
- name: tokenize_and_apply_chat_template_with_masking
180+
arguments:
181+
remove_columns: all
182+
fn_kwargs:
183+
max_seq_length: 4096
184+
conversation_column_name: "messages"
185+
```
186+
187+
Example training data:
188+
189+
```json
190+
{"messages": [{"content": "You are an AI language model developed by IBM Research. You are a cautious assistant. You carefully follow instructions. You are helpful and harmless and you follow ethical guidelines and promote positive behavior.", "role": "system"}, {"content": "Using the word \"grace\", come up with a word that rhymes and has the same number of syllables\n<nopace>", "role": "user"}, {"content": "Certainly! Here's a word that rhymes with \"grace\" and has the same number of syllables:\n1\\. Space", "role": "assistant"}, {"content": "Using the word \"grace\", come up with a word that rhymes and has the same number of syllables\n<nopace>", "role": "user"}, {"content": "Certainly! Here's a word that rhymes with \"grace\" and has the same number of syllables:\n1\\. Space", "role": "assistant"}], "group": "lab_extension", "dataset": "base/full-extension", "metadata": "{\"num_turns\": 2}"}
191+
192+
{"messages": [{"content": "You are an AI language model developed by IBM Research. You are a cautious assistant. You carefully follow instructions. You are helpful and harmless and you follow ethical guidelines and promote positive behavior.", "role": "system"}, {"content": "Tell me one word that rhymes and has the opposite meaning of \"open\".", "role": "user"}, {"content": "Sure! Here's a word that rhymes with \"open\" and has the opposite meaning:\n1\\. Shut", "role": "assistant"}, {"content": "Tell me one word that rhymes and has the opposite meaning of \"open\".", "role": "user"}, {"content": "Sure! Here's a word that rhymes with \"open\" and has the opposite meaning:\n1\\. Shut", "role": "assistant"}], "group": "lab_extension", "dataset": "base/full-extension", "metadata": "{\"num_turns\": 2}"}
193+
```
194+
195+
For example if we want to perform instruction-tuning on the `granite-3.1-8b-base` model, which is a base (non-instruction-tuned) model, we provide the chat template from the "ibm-granite/granite-3.1-8b-instruct" model using the config's `dataprocessor.chat_template` parameter. Since the special tokens referenced in this chat template are not present in the base model by default, they should be added explicitly through the `add_special_tokens` field in the tuning config.
196+
197+
If the model being used is already instruction-tuned, you should update or remove the `dataprocessor.chat_template` field from the data config and `add_special_tokens` field from the tuning config as appropriate, based on the `chat_template` and `additional_special_tokens` defined in the model’s `tokenizer_config.json`.
198+
199+
The `tokenize_and_apply_chat_template_with_masking` data handler is used to apply the chat template and tokenize the data. The `conversation_column_name` field in the data handler is used for specifying the key/field in the dataset that contains the conversation data, which is `messages` in the example training data provided above. You might need to update the `conversation_column_name` based on your dataset. As this data handler performs tokenization and generates the `input_ids`, `labels`, and `attention_masks` fields, it is not necessary to specify the `instruction_template` and `response_template` in the tuning config.
200+
201+
If the data is already tokenized, then all the `data_handlers` should be omitted or commented out.

‎docs/images/data_config_guide.png‎

957 KB
Loading

0 commit comments

Comments
 (0)