Text Generation
Transformers
Safetensors
English
qwen2
conversational
text-generation-inference
krogoldAI commited on
Commit
5c38700
·
verified ·
1 Parent(s): 460fdc5

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +376 -181
README.md CHANGED
@@ -1,6 +1,12 @@
1
  ---
2
  library_name: transformers
3
- tags: []
 
 
 
 
 
 
4
  ---
5
 
6
  # QueryRefiner-0.5B-v0.1-GRPO
@@ -17,6 +23,295 @@ This model addresses a critical challenge in RAG systems: converting ambiguous,
17
 
18
  **Note:** This model is currently in an experimental, beta stage. It represents an initial release focused on establishing baseline capabilities. Future iterations may address current limitations, expand domain coverage, or incorporate additional output features based on real-world deployment feedback.
19
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
20
 
21
  # Model Card for Model ID
22
 
@@ -66,6 +361,14 @@ WARMUP_STEPS = 50
66
  |Confidence|3.1%|99.9%|100%|99.9%|
67
  |Perfectly structured output|0.0%|99.8%|99.8%|99.9%| -->
68
 
 
 
 
 
 
 
 
 
69
  #### Table 2 - Semantic scores
70
 
71
  |Metric|QueryRefiner-0.5B-v0.1-SFT|QueryRefiner-0.5B-v0.1-GRPO|
@@ -91,191 +394,83 @@ WARMUP_STEPS = 50
91
 
92
  (Corrected for the SFT + GRPO-SFT models)
93
 
94
- ## Model Details
95
-
96
- ### Model Description
97
-
98
- <!-- Provide a longer summary of what this model is. -->
99
-
100
- This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
101
-
102
- - **Developed by:** [More Information Needed]
103
- - **Funded by [optional]:** [More Information Needed]
104
- - **Shared by [optional]:** [More Information Needed]
105
- - **Model type:** [More Information Needed]
106
- - **Language(s) (NLP):** [More Information Needed]
107
- - **License:** [More Information Needed]
108
- - **Finetuned from model [optional]:** [More Information Needed]
109
-
110
- ### Model Sources [optional]
111
-
112
- <!-- Provide the basic links for the model. -->
113
-
114
- - **Repository:** [More Information Needed]
115
- - **Paper [optional]:** [More Information Needed]
116
- - **Demo [optional]:** [More Information Needed]
117
-
118
- ## Uses
119
-
120
- <!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
121
-
122
- ### Direct Use
123
-
124
- <!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
125
-
126
- [More Information Needed]
127
-
128
- ### Downstream Use [optional]
129
-
130
- <!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
131
-
132
- [More Information Needed]
133
-
134
- ### Out-of-Scope Use
135
 
136
- <!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
 
137
 
138
- [More Information Needed]
139
-
140
- ## Bias, Risks, and Limitations
141
-
142
- <!-- This section is meant to convey both technical and sociotechnical limitations. -->
143
-
144
- [More Information Needed]
145
-
146
- ### Recommendations
147
-
148
- <!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
149
-
150
- Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
151
-
152
- ## How to Get Started with the Model
153
-
154
- Use the code below to get started with the model.
155
-
156
- [More Information Needed]
157
-
158
- ## Training Details
159
-
160
- ### Training Data
161
-
162
- <!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
163
-
164
- [More Information Needed]
165
-
166
- ### Training Procedure
167
-
168
- <!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
169
-
170
- #### Preprocessing [optional]
171
-
172
- [More Information Needed]
173
-
174
-
175
- #### Training Hyperparameters
176
-
177
- - **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
178
-
179
- #### Speeds, Sizes, Times [optional]
180
-
181
- <!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
182
-
183
- [More Information Needed]
184
-
185
- ## Evaluation
186
-
187
- <!-- This section describes the evaluation protocols and provides the results. -->
188
-
189
- ### Testing Data, Factors & Metrics
190
-
191
- #### Testing Data
192
-
193
- <!-- This should link to a Dataset Card if possible. -->
194
-
195
- [More Information Needed]
196
-
197
- #### Factors
198
-
199
- <!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
200
-
201
- [More Information Needed]
202
-
203
- #### Metrics
204
-
205
- <!-- These are the evaluation metrics being used, ideally with a description of why. -->
206
-
207
- [More Information Needed]
208
-
209
- ### Results
210
-
211
- [More Information Needed]
212
-
213
- #### Summary
214
-
215
-
216
-
217
- ## Model Examination [optional]
218
-
219
- <!-- Relevant interpretability work for the model goes here -->
220
-
221
- [More Information Needed]
222
-
223
- ## Environmental Impact
224
-
225
- <!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
226
-
227
- Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
228
-
229
- - **Hardware Type:** [More Information Needed]
230
- - **Hours used:** [More Information Needed]
231
- - **Cloud Provider:** [More Information Needed]
232
- - **Compute Region:** [More Information Needed]
233
- - **Carbon Emitted:** [More Information Needed]
234
-
235
- ## Technical Specifications [optional]
236
-
237
- ### Model Architecture and Objective
238
-
239
- [More Information Needed]
240
-
241
- ### Compute Infrastructure
242
-
243
- [More Information Needed]
244
-
245
- #### Hardware
246
-
247
- [More Information Needed]
248
-
249
- #### Software
250
-
251
- [More Information Needed]
252
-
253
- ## Citation [optional]
254
-
255
- <!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
256
-
257
- **BibTeX:**
258
-
259
- [More Information Needed]
260
-
261
- **APA:**
262
-
263
- [More Information Needed]
264
-
265
- ## Glossary [optional]
266
-
267
- <!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
268
-
269
- [More Information Needed]
270
 
271
- ## More Information [optional]
272
 
273
- [More Information Needed]
274
 
275
- ## Model Card Authors [optional]
276
 
277
- [More Information Needed]
278
 
279
- ## Model Card Contact
280
 
281
- [More Information Needed]
 
1
  ---
2
  library_name: transformers
3
+ datasets:
4
+ - krogoldAI/rag-query-analysis
5
+ - krogoldAI/rag-ambiguous-queries
6
+ language:
7
+ - en
8
+ base_model:
9
+ - Qwen/Qwen2.5-0.5B-Instruct
10
  ---
11
 
12
  # QueryRefiner-0.5B-v0.1-GRPO
 
23
 
24
  **Note:** This model is currently in an experimental, beta stage. It represents an initial release focused on establishing baseline capabilities. Future iterations may address current limitations, expand domain coverage, or incorporate additional output features based on real-world deployment feedback.
25
 
26
+ ## Examples
27
+
28
+ <details>
29
+ <summary><i>Unroll to see Example #1</i></summary>
30
+
31
+ User query:
32
+
33
+ >Was his mother tall?
34
+
35
+ Model output:
36
+
37
+ ```xml
38
+ <query_analysis>
39
+ <domain ambiguous="true">
40
+ <candidate confidence="0.6">Biography</candidate>
41
+ <candidate confidence="0.4">Factual Information</candidate>
42
+ </domain>
43
+ <intent ambiguous="true">
44
+ <candidate confidence="0.7">Factual Question</candidate>
45
+ <candidate confidence="0.3">Interpretation</candidate>
46
+ </intent>
47
+ <concepts>
48
+ <explicit>mother</explicit>
49
+ </concepts>
50
+ <relations>
51
+ <relation subject="mother" predicate="height" object="[PERSON]"/>
52
+ </relations>
53
+ <insufficient_context>false</insufficient_context>
54
+ <rephrased>true</rephrased>
55
+ <rephrased_query>Is [PERSON]'s mother tall?</rephrased_query>
56
+ </query_analysis>
57
+ ```
58
+
59
+ </details>
60
+
61
+ <details>
62
+ <summary><i>Unroll to see Example #2</i></summary>
63
+
64
+ User query:
65
+
66
+ >Which legal aspects of data gathering must be considered before training a language model?
67
+
68
+ Model output:
69
+
70
+ ```xml
71
+ <query_analysis>
72
+ <domain ambiguous="false">
73
+ <candidate confidence="1.0">Legal</candidate>
74
+ </domain>
75
+ <intent ambiguous="false">
76
+ <candidate confidence="1.0">Data privacy and ethics</candidate>
77
+ </intent>
78
+ <concepts>
79
+ <explicit>data gathering, language models</explicit>
80
+ <implicit>legal considerations, ethical practices</implicit>
81
+ </concepts>
82
+ <relations>
83
+ <relation subject="data gathering" predicate="must consider" object="legal aspects"/>
84
+ <relation subject="language models" predicate="require" object="legal considerations"/>
85
+ </relations>
86
+ <insufficient_context>false</insufficient_context>
87
+ <rephrased>true</rephrased>
88
+ <rephrased_query>legal requirements for data collection and usage when developing natural language processing models</rephrased_query>
89
+ </query_analysis>
90
+ ```
91
+
92
+ </details>
93
+
94
+ <details>
95
+ <summary><i>Unroll to see Example #3</i></summary>
96
+
97
+ User query:
98
+
99
+ > How do they enhance its performance?
100
+
101
+ Model output:
102
+
103
+ ```xml
104
+ <query_analysis>
105
+ <domain ambiguous="true">
106
+ <candidate confidence="0.5">Technology</candidate>
107
+ <candidate confidence="0.5">Engineering</candidate>
108
+ </domain>
109
+ <intent ambiguous="true">
110
+ <candidate confidence="0.6">Performance enhancement</candidate>
111
+ <candidate confidence="0.4">Troubleshooting</candidate>
112
+ </intent>
113
+ <concepts>
114
+ <explicit>performance</explicit>
115
+ <implicit>[TECHNOLOGY/ENGINEERING] capabilities</implicit>
116
+ </concepts>
117
+ <insufficient_context>true</insufficient_context>
118
+ <rephrased>true</rephrased>
119
+ <rephrased_query>how do [TECHNOLOGY/ENGINEERING] enhancements improve [PRODUCT/SERVICE] performance</rephrased_query>
120
+ </query_analysis>
121
+ ```
122
+
123
+ </details>
124
+
125
+
126
+ ## Intended Use
127
+
128
+ The model is designed to serve as a query analysis layer in RAG systems, where it processes user inputs before they are sent to retrieval components. It can handle queries with varying degrees of ambiguity and identify when queries lack sufficient context for effective retrieval. The structured XML output enables downstream systems to make informed decisions about how to handle each query based on confidence scores, ambiguity flags, and the rephrased version.
129
+
130
+ Typical deployment scenarios include conversational search systems, question-answering platforms, document retrieval services, and any application where understanding user intent and optimizing queries for semantic search is critical. The model's compact 0.5B parameter size makes it suitable for deployment in resource-constrained environments or as part of larger multi-component systems where latency is a concern.
131
+
132
+ ## Training Data
133
+
134
+ The model was trained on the [krogoldAI/rag-query-analysis](https://huggingface.co/datasets/krogoldAI/rag-query-analysis) dataset, which contains 7,305 high-quality query-analysis pairs. This dataset was carefully curated from three sources:
135
+ - [rag-datasets/rag-mini-wikipedia](https://huggingface.co/datasets/rag-datasets/rag-mini-wikipedia)
136
+ - [razbit96/Ambiguity-Handling-in-User-Queries](https://huggingface.co/datasets/razbit96/Ambiguity-Handling-in-User-Queries)
137
+ - [glaiveai/RAG-v1](https://huggingface.co/datasets/glaiveai/RAG-v1).
138
+
139
+ Approximately 20% of the training examples include queries with systematically introduced ambiguity at varying levels to ensure the model can handle realistic user inputs across the ambiguity spectrum.
140
+
141
+ The training data underwent rigorous quality assurance through a dual evaluation framework. Each example was validated for strict XML schema conformance and semantically evaluated using an LLM-as-a-judge protocol with six quality dimensions. Only examples achieving both perfect structural validity and high semantic quality scores were included in the final dataset, ensuring the model was trained exclusively on gold-standard examples.
142
+
143
+ ## Training Procedure
144
+
145
+ The model underwent full fine-tuning (not parameter-efficient methods like LoRA) of all parameters in [Qwen2.5-0.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct). Training was conducted over three epochs with a per-device batch size of 4 and gradient accumulation over 4 steps, yielding an effective batch size of 16. The learning rate was set to 2e-5 with a weight decay of 0.01 to prevent overfitting. A warmup period of 100 steps allowed the model to gradually adapt to the task-specific distribution before reaching the full learning rate. Training was performed on an NVIDIA A100 SXM GPU.
146
+
147
+ The training code can be found [here](Code/Fine-tuning.py).
148
+
149
+ ## Model Capabilities
150
+
151
+ The model employs a systematic, ontology-inspired analysis framework that decomposes queries into structured XML representations. This analytical approach (which identifies domains, intents, concepts, relations, and ambiguities) aims to enhance the quality of the rephrased query output. For every query, it provides domain classification and intent detection with confidence scores that sum to `1.0`, properly handling both unambiguous cases (single candidate with confidence `1.0`) and ambiguous cases (multiple candidates with distributed confidence). The model can optionally extract explicit and implicit concepts, identify relations between entities using subject-predicate-object triples, and normalize ambiguous terms when disambiguation would improve retrieval.
152
+
153
+ The rephrasing capability focuses on retrieval optimization rather than query answering. The model transforms queries by using specific terminology likely to appear in relevant documents, expanding acronyms when contextually appropriate, adding disambiguating context, and making implicit references explicit through placeholder notation such as `[PERSON]` or `[COMPANY]`. Importantly, the model has learned to preserve already-optimal queries unchanged, recognizing when rephrasing would not improve retrieval effectiveness.
154
+
155
+ This structured analytical framework ensures that rephrasings are informed by comprehensive query understanding rather than surface-level transformations, leading to more semantically precise retrieval-optimized queries.
156
+
157
+ The default output schema is the following:
158
+
159
+ ```xml
160
+ <query_analysis>
161
+ <domain ambiguous="true|false">
162
+ <candidate confidence="X.X">...</candidate>
163
+ </domain>
164
+ <intent ambiguous="true|false">
165
+ <candidate confidence="X.X">...</candidate>
166
+ </intent>
167
+ <!-- Optional sections -->
168
+ <concepts>
169
+ <explicit>...</explicit>
170
+ <implicit>...</implicit>
171
+ </concepts>
172
+ <relations>
173
+ <relation subject="..." predicate="..." object="..."/>
174
+ </relations>
175
+ <normalized_terms>
176
+ <term original="..." normalized="..."/>
177
+ </normalized_terms>
178
+ <!-- End optional sections -->
179
+ <insufficient_context>true|false</insufficient_context>
180
+ <rephrased>true|false</rephrased>
181
+ <rephrased_query>...</rephrased_query>
182
+ </query_analysis>
183
+ ```
184
+
185
+ ## Limitations and Considerations
186
+
187
+ As a 0.5B parameter model, QueryRefiner-0.5B-v0.1-GRPO prioritizes efficiency and deployability over the capabilities of larger language models. While it performs well on the types of queries represented in its training distribution, performance may degrade on highly specialized domains, multilingual queries, or query types significantly different from the training examples. The model focuses exclusively on English-language queries and has been optimized for the specific XML output format defined in its training.
188
+
189
+ The model's ambiguity detection and confidence scoring reflect patterns learned from the training data, which includes both natural and synthetically augmented ambiguous queries. While the training process incorporated diverse ambiguity levels, edge cases or novel forms of ambiguity may not be handled with the same reliability as more common patterns. Users should consider the model's confidence scores as informative signals rather than calibrated probabilities.
190
+
191
+ ## Usage Example
192
+
193
+ First, make sure you have the latest version of `transformers`:
194
+
195
+ ```shell
196
+ pip install git+https://github.com/huggingface/transformers.git
197
+ ```
198
+
199
+ Define the system prompt (since it was used as such during training, for optimal results we recommend not changing it).
200
+
201
+ <details>
202
+ <summary><i>Unroll to see the system prompt</i></summary>
203
+
204
+ ```python
205
+ SYSTEM_PROMPT = """You are a query analysis and rephraser for a Retrieval-Augmented Generation (RAG) system.
206
+ Your sole task is to **analyze user queries** and output a structured XML document.
207
+ You must **not answer the query itself**, only analyze and rephrase it.
208
+
209
+ ## RAG Query Optimization
210
+
211
+ Effective rephrasing should optimize for document retrieval by:
212
+ - Using **specific terminology** and domain vocabulary likely to appear in relevant documents
213
+ - **Expanding acronyms** when they add context (but not when the acronym itself is the subject)
214
+ - **Adding disambiguating context** without over-constraining the search
215
+ - **Making implicit references explicit** using placeholders for missing entities (e.g., [PERSON], [COMPANY])
216
+ - **Preserving user intent** while improving retrieval precision
217
+
218
+ Examples: "How do I reset my password?" → "password reset procedure authentication"
219
+ "What's their revenue?" → "What's [COMPANY]'s revenue?"
220
+
221
+ ## Analysis Process
222
+
223
+ Follow this systematic approach to decompose each query:
224
+ 1. **Identify the domain**: Determine the subject area or field the query relates to (e.g., banking, healthcare, technology, legal). Consider both explicit domain indicators and contextual clues.
225
+ 2. **Determine the intent**: Classify what the user is trying to accomplish (e.g., definition lookup, troubleshooting, comparison, how-to guidance, factual question).
226
+ 3. **Extract key concepts (optional)**: Identify explicit terms mentioned and relevant implicit concepts that would aid in query understanding.
227
+ 4. **Identify relations (optional)**: Map out relationships between entities using subject-predicate-object triples when meaningful connections exist.
228
+ 5. **Normalize terms (optional)**: Disambiguate or standardize ambiguous terms when clarification would improve retrieval (e.g., "Apple" → "Apple Inc." vs "apple fruit").
229
+ 6. **Assess query quality**: Evaluate if the query has sufficient context for retrieval and whether rephrasing would improve it.
230
+ 7. **Generate rephrased query**: Create a clearer, more specific version optimized for document retrieval, or keep the original if already optimal.
231
+
232
+ ## Technical Rules
233
+
234
+ 1. **Never answer the user's question.** Only analyze and rephrase.
235
+ 2. Always produce valid XML strictly following the schema below.
236
+ 3. `<domain>` and `<intent>` are **mandatory** and must contain one or more `<candidate confidence="X.X">...</candidate>` entries:
237
+ - Confidence scores must always sum to 1.0
238
+ - If unambiguous: **exactly one candidate** with `confidence="1.0"` and `ambiguous="false"`
239
+ - If ambiguous: multiple candidates with `ambiguous="true"` and confidence distributed proportionally to plausibility:
240
+ - Use uniform distribution only when candidates are genuinely equally likely
241
+ - Otherwise, weight confidence toward the more probable interpretation
242
+ - Examples:
243
+ - "What is Mercury's rotation period?" → Astronomy 0.5, Chemistry 0.5 (equally plausible)
244
+ - "Jaguar speed in the wild" → Zoology 0.8, Automotive 0.2 (context favors animal)
245
+ 4. Confidence values must always have one decimal place (e.g., `0.5`, `1.0`).
246
+ 5. Only `<concepts>`, `<relations>`, and `<normalized_terms>` are optional. **All other elements are mandatory.**
247
+ 6. `<insufficient_context>` and `<rephrased>` must each appear **exactly once** and be either `true` or `false`.
248
+ 7. `<rephrased_query>` must always appear, even if identical to the input.
249
+ 8. **Output only valid XML.** Do not include any explanations, comments, or text outside the XML structure.
250
+ 9. All elements must appear in the order specified in the schema:
251
+ `<domain> → <intent> → <concepts> → <relations> → <normalized_terms> → <insufficient_context> → <rephrased> → <rephrased_query>`.
252
+
253
+ ## Output Schema
254
+
255
+ <query_analysis>
256
+ <domain ambiguous="true|false">
257
+ <candidate confidence="X.X">...</candidate>
258
+ </domain>
259
+ <intent ambiguous="true|false">
260
+ <candidate confidence="X.X">...</candidate>
261
+ </intent>
262
+ <!-- Optional sections -->
263
+ <concepts>
264
+ <explicit>...</explicit>
265
+ <implicit>...</implicit>
266
+ </concepts>
267
+ <relations>
268
+ <relation subject="..." predicate="..." object="..."/>
269
+ </relations>
270
+ <normalized_terms>
271
+ <term original="..." normalized="..."/>
272
+ </normalized_terms>
273
+ <!-- End optional sections -->
274
+ <insufficient_context>true|false</insufficient_context>
275
+ <rephrased>true|false</rephrased>
276
+ <rephrased_query>...</rephrased_query>
277
+ </query_analysis>
278
+ """
279
+ ```
280
+ </details>
281
+
282
+ Then, use the code below to get started with the model.
283
+
284
+ ```python
285
+ from transformers import AutoTokenizer, AutoModelForCausalLM
286
+
287
+ model_name = "krogoldAI/QueryRefiner-0.5B-v0.1-GRPO"
288
+ tokenizer = AutoTokenizer.from_pretrained(model_name)
289
+ model = AutoModelForCausalLM.from_pretrained(model_name)
290
+
291
+ user_query = "How do I reset my password?"
292
+
293
+ messages = [
294
+ {"role": "system", "content": SYSTEM_PROMPT},
295
+ {"role": "user", "content": user_query}
296
+ ]
297
+
298
+ input_text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
299
+ inputs = tokenizer(input_text, return_tensors="pt")
300
+
301
+ outputs = model.generate(**inputs, max_new_tokens=512)
302
+ analysis = tokenizer.decode(outputs[0], skip_special_tokens=True)
303
+
304
+ print(analysis)
305
+ ```
306
+
307
+ ## Evaluation and Performance
308
+
309
+ <!-- The model was trained on data that passed stringent quality thresholds, with all training examples achieving perfect structural conformance and semantic quality scores of 4 or higher across six evaluation dimensions: domain accuracy, intent accuracy, ambiguity assessment, rephrasing quality, intent preservation, and guideline adherence. This ensures the model learned from consistently high-quality demonstrations of the desired behavior. -->
310
+
311
+ ### Structural Validation
312
+
313
+ To assess the model's ability to produce correctly formatted outputs, we evaluated structural conformance across 1,000 examples from the test split of [krogoldAI/rag-ambiguous-queries](https://huggingface.co/datasets/krogoldAI/rag-ambiguous-queries), comparing QueryRefiner-0.5B-v0.1 against its base model [Qwen2.5-0.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct). The evaluation measured adherence to the required XML schema, including tag presence, well-formedness, element ordering, and confidence score formatting.
314
+
315
 
316
  # Model Card for Model ID
317
 
 
361
  |Confidence|3.1%|99.9%|100%|99.9%|
362
  |Perfectly structured output|0.0%|99.8%|99.8%|99.9%| -->
363
 
364
+ Here, *tag structure* verifies that all required XML tags are present, *XML validity* ensures the output is well-formed and parseable, *order* confirms that required tags appear in the correct sequence, and *confidence* validates that confidence values are properly formatted and sum to `1.0`.
365
+
366
+ <!-- The results demonstrate that fine-tuning substantially improved structural reliability, with QueryRefiner achieving near-perfect conformance (99.6%) compared to the base model's inability to produce any fully compliant outputs. -->
367
+
368
+ ### Semantic Validation
369
+
370
+ Beyond structural correctness, we evaluated the semantic quality of the model's outputs using an LLM-as-a-judge protocol with GPT5 on 1,000 examples from the test split of [krogoldAI/rag-ambiguous-queries](https://huggingface.co/datasets/krogoldAI/rag-ambiguous-queries). Each output was assessed across six dimensions aligned with the model's core objectives.
371
+
372
  #### Table 2 - Semantic scores
373
 
374
  |Metric|QueryRefiner-0.5B-v0.1-SFT|QueryRefiner-0.5B-v0.1-GRPO|
 
394
 
395
  (Corrected for the SFT + GRPO-SFT models)
396
 
397
+ All values are reported as mean ± standard deviation (%), computed over test examples. The base model produced too few valid XML samples for meaningful semantic evaluation.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
398
 
399
+ <details>
400
+ <summary><i>Unroll to see the system prompt used for the "judge" LLM</i></summary>
401
 
402
+ ```py
403
+ JUDGE_PROMPT = """You are evaluating query analyses for a RAG system.
404
+
405
+ ### System Requirements
406
+ The analyzer was instructed to optimize queries for document retrieval by:
407
+ - Using **specific terminology** and domain vocabulary likely to appear in relevant documents
408
+ - **Expanding acronyms** when they add context (but not when the acronym itself is the subject)
409
+ - **Adding disambiguating context** without over-constraining the search
410
+ - **Making implicit references explicit** using placeholders for missing entities (e.g., [PERSON], [COMPANY])
411
+ - **Preserving user intent** while improving retrieval precision
412
+ - **Keeping the original query unchanged** if it's already well-optimized for retrieval
413
+
414
+ ### Input
415
+ Original: "{original}"
416
+ Domain: {domain}
417
+ Intent: {intent}
418
+ Rephrased: "{rephrased}"
419
+
420
+ Note: The [ambiguous] tag indicates the analyzer determined the query has multiple plausible interpretations for that dimension, with confidence distributed across candidates.
421
+
422
+ ### Evaluation Criteria (1-5 scale)
423
+
424
+ 1. Domain Accuracy (1=wrong, 3=acceptable, 5=perfect)
425
+ - Are the domain candidates correct?
426
+ - Are confidence scores reasonable?
427
+
428
+ 2. Intent Accuracy (1=wrong, 3=acceptable, 5=perfect)
429
+ - Are the intent candidates correct?
430
+ - Are confidence scores reasonable?
431
+
432
+ 3. Ambiguity Assessment (1=wrong, 3=acceptable, 5=perfect)
433
+ - Is the ambiguity determination appropriate for this query?
434
+ - If ambiguous: Is the confidence distribution justified?
435
+ - If clearly unambiguous but marked ambiguous (or vice versa), score ≤2.
436
+
437
+ 4. Rephrasing Quality
438
+ 1 = Poor (significantly degraded the query, or completely failed to address clear issues)
439
+ 2 = Suboptimal (minor degradation, or missed an obvious improvement opportunity)
440
+ 3 = Neutral (minor changes with mixed effects)
441
+ 4 = Good improvement, but could be better
442
+ 5 = Optimal outcome (either improved a suboptimal query, or correctly preserved an already-optimal one)
443
+ (Note: Do not penalize rephrasing for being minimal if the original was already optimal.)
444
+
445
+ 5. Intent Preservation (1=lost, 3=mostly preserved, 5=fully preserved)
446
+ - Focus on meaning fidelity, not retrieval optimization.
447
+
448
+ 6. Follows Guidelines (1=violates, 3=mostly follows, 5=perfectly follows)
449
+ - Check adherence to the RAG optimization principles above.
450
+
451
+ ### Output Format
452
+ {{
453
+ "domain_accuracy": <1-5>,
454
+ "intent_accuracy": <1-5>,
455
+ "ambiguity_assessment": <1-5>,
456
+ "rephrasing_quality": <1-5>,
457
+ "intent_preservation": <1-5>,
458
+ "follows_guidelines": <1-5>,
459
+ "critical_issue": "<brief description or null>",
460
+ "usable": <true/false> // true if suitable for RAG use, even if not perfect
461
+ }}
462
+
463
+ Output only valid JSON. Do not include any explanations, comments, or text outside the JSON structure.
464
+ """
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
465
 
466
+ ```
467
 
468
+ </details>
469
 
470
+ ### Performance Considerations
471
 
472
+ Performance characteristics will vary based on query type, domain, and ambiguity level. The model is expected to perform strongest on queries similar to those in the training distribution and may require additional fine-tuning or prompt engineering for specialized applications or domains underrepresented in the training data.
473
 
474
+ ## Acknowledgments
475
 
476
+ This model builds upon [Qwen2.5-0.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct) by the Qwen team at Alibaba Cloud. The training data incorporates queries from [rag-datasets/rag-mini-wikipedia](https://huggingface.co/datasets/rag-datasets/rag-mini-wikipedia), [razbit96/Ambiguity-Handling-in-User-Queries](https://huggingface.co/datasets/razbit96/Ambiguity-Handling-in-User-Queries), and [glaiveai/RAG-v1](https://huggingface.co/datasets/glaiveai/RAG-v1).