File size: 3,723 Bytes
e0ed027
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
---
base_model: mistralai/Ministral-3-8B-Instruct-2512-BF16
model_name: opensearch-agentic-dsl
library_name: peft
pipeline_tag: text-generation
license: apache-2.0
language:
- en
tags:
- base_model:adapter:mistralai/Ministral-3-8B-Instruct-2512-BF16
- lora
- qlora
- sft
- transformers
- trl
- opensearch
- text-to-dsl
---

# opensearch-agentic-dsl

A LoRA adapter that translates English shopper requests into OpenSearch DSL for
a second-hand luxury catalog. It is designed for OpenSearch's native Agentic
Search `QueryPlanningTool`.

The adapter uses
[mistralai/Ministral-3-8B-Instruct-2512-BF16](https://huggingface.co/mistralai/Ministral-3-8B-Instruct-2512-BF16)
at revision `06cc81bfd6e45321d8fc8f816576c5b6ac67ec22`. Load both the base
model and tokenizer at this revision, then attach the adapter with PEFT.

## Input and output

Input combines shopper text, trusted application controls, the index mapping,
and allowed query fields. The exact [system prompt](prompts/system.txt) and
[user template](prompts/user.txt) are included. The
[complete example](example.py) shows how to construct the three-line question
and double JSON encode the mapping and field list.

Output is one JSON request body containing `size`, integer `track_total_hits`,
`query`, and optional `sort`. The planner applies required filters, price
ceilings, and the selected ranking mode. Persona expansion contributes optional
scoring. Index selection, search pipelines, and `_source` stay application-owned.

## Run the model

Download `sharp-pixel/opensearch-agentic-dsl` and run the included example:

```bash
hf download sharp-pixel/opensearch-agentic-dsl --local-dir opensearch-agentic-dsl
cd opensearch-agentic-dsl
python example.py
```

The example requires a CUDA GPU with enough memory for the BF16 base model and
uses Transformers 5.13.0, PEFT 0.19.1, and PyTorch 2.13.0. It loads the bundled
prompts and local adapter, uses greedy decoding, and prints the generated body.
Set `ADAPTER_ID=sharp-pixel/opensearch-agentic-dsl` to load the adapter from the
Hub instead.

For vLLM, enable LoRA with maximum rank 16, load the language model only, and
serve the adapter as `opensearch-agentic-dsl`.

## Training and evaluation

Training used 4,640 synthetic examples and 1,160 held-out examples, grouped to
keep related scenarios within a single split. Only the language-model attention
and MLP projections were adapted; the vision encoder and projector stayed frozen.

| Setting | Value |
| --- | --- |
| Method | QLoRA with completion-only supervision |
| Quantization / compute | 4-bit NF4 / BF16 |
| LoRA rank / alpha / dropout | 16 / 32 / 0.05 |
| Epochs / sequence length | 2 / 2,112 tokens |
| Learning rate / effective batch size | 0.0001 / 16 |
| GPU / training time | RTX PRO 6000 Blackwell / 1.76 hours |

| Metric | Value |
| --- | ---: |
| Training loss | 0.0038393672 |
| Held-out loss | 0.0016606329 |
| Held-out token accuracy | 99.9305% |

Token accuracy is measured with teacher-forced targets, not freely generated
requests. The synthetic evaluation does not establish real-world retrieval
quality. Validate generated DSL against the actual mapping and application
policy, and enforce OpenSearch permissions and resource limits.

Training data, prompts, policy, and the dependency lockfile match this
[verified source revision](https://github.com/sharp-pixel/LaTrouvaille/tree/7b26a2a56b71eab674ad8d53be5c1d06353967c8/query-understanding-training).

## License

The adapter and accompanying model-card documentation are released under
[Apache 2.0](LICENSE). The upstream model and tokenizer are also Apache 2.0;
see [NOTICE](NOTICE) for attribution. Application source and training data retain
their respective licenses.