Update README.md

README.md

@@ -1,202 +1,198 @@
 ---
 base_model: Qwen/Qwen2.5-7B
 library_name: peft
+language:
+- en
+license: agpl-3.0
+datasets:
+- OramaSearch/nlp-to-query-small
 ---
 
-# Model Card for Model ID
-
-<!-- Provide a quick summary of what the model is/does. -->
+# Query Translator Mini
 
+This repository contains a fine-tuned version of Qwen 2.5 7B model specialized in translating natural language queries into structured Orama search queries.
 
+The model uses PEFT with LoRA to maintain efficiency while achieving high performance.
 
 ## Model Details
 
 ### Model Description
 
-<!-- Provide a longer summary of what this model is. -->
-
-
-
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
-
-### Model Sources [optional]
-
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
-
-## Uses
-
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
-### Direct Use
-
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
-
-[More Information Needed]
-
-### Downstream Use [optional]
-
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
-
-### Out-of-Scope Use
-
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
-
-[More Information Needed]
-
-## Bias, Risks, and Limitations
-
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
-
-### Recommendations
-
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
-
-## How to Get Started with the Model
-
-Use the code below to get started with the model.
-
-[More Information Needed]
+The Query Translator Mini model is designed to convert natural language queries into structured JSON queries compatible with the Orama search engine.
+
+It understands various data types and query operators, making it versatile for different search scenarios.
+
+### Key Features
+
+- Translates natural language to structured Orama queries
+- Supports multiple field types: string, number, boolean, enum, and arrays
+- Handles complex query operators: `gt`, `gte`, `lt`, `lte`, `eq`, `between`, `containsAll`
+- Supports nested properties with dot notation
+- Works with both full-text search and filtered queries
+
+## Usage
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+# Load the model and tokenizer
+model_name = "your-username/query-translator-mini"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForCausalLM.from_pretrained(model_name)
+
+# System Prompt used during training
+SYSTEM_PROMPT = """
+You are a tool used to generate synthetic data of Orama queries. Orama is a full-text, vector, and hybrid search engine.
+
+Let me show you what you need to do with some examples.
+
+Example:
+  - Query: `"What are the red wines that cost less than 20 dollars?"`
+  - Schema: `{ "name": "string", "content": "string", "price": "number", "tags": "enum[]" }`
+  - Generated query: `{ "term": "", "where": { "tags": { "containsAll": ["red", "wine"] }, "price": { "lt": 20 } } }`
+
+Another example:
+  - Query: `"Show me 5 prosecco wines good for aperitif"`
+  - Schema: `{ "name": "string", "content": "string", "price": "number", "tags": "enum[]" }`
+  - Generated query: `{ "term": "prosecco aperitif", "limit": 5 }`
+
+One last example:
+  - Query: `"Show me some wine reviews with a score greater than 4.5 and less than 5.0."`
+  - Schema: `{ "title": "string", "content": "string", "reviews": { "score": "number", "text": "string" } }]`
+  - Generated query: `{ "term": "", "where": { "reviews.score": { "between": [4.5, 5.0] } } }`
+
+The rules to generate the query are:
+
+- Never use an "embedding" field in the schema.
+- Every query has a "term" field that is a string. It represents the full-text search terms. Can be empty (will match all documents).
+- You can use a "where" field that is an object. It represents the filters to apply to the documents. Its keys and values depend on the schema of the database:
+  - If the field is a "string", you should not use operators. Example: `{ "where": { "title": "champagne" } }`.
+  - If the field is a "number", you can use the following operators: "gt", "gte", "lt", "lte", "eq", "between". Example: `{ "where": { "price": { "between": [20, 100] } } }`. Another example: `{ "where": { "price": { "lt": 20 } } }`.
+  - If the field is an "enum", you can use the following operators: "eq", "in", "nin". Example: `{ "where": { "tags": { "containsAll": ["red", "wine"] } } }`.
+  - If the field is an "string[]", it's gonna be just like the "string" field, but you can use an array of values. Example: `{ "where": { "title": ["champagne", "montagne"] } }`.
+  - If the field is a "boolean", you can use the following operators: "eq". Example: `{ "where": { "isAvailable": true } }`. Another example: `{ "where": { "isAvailable": false } }`.
+  - If the field is a "enum[]", you can use the following operators: "containsAll". Example: `{ "where": { "tags": { "containsAll": ["red", "wine"] } } }`.
+  - Nested properties are supported. Just translate them into dot notation. Example: `{ "where": { "author.name": "John" } }`.
+  - Array of numbers are not supported.
+  - Array of booleans are not supported.
+"""
+
+# Example query
+query = "What are the red wines that cost less than 20 dollars?"
+
+# Orama schema
+schema = {
+    "name": "string",
+    "content": "string",
+    "price": "number",
+    "tags": "enum[]"
+}
+
+# Generate structured query
+messages = [
+    {"role": "system", "content": SYSTEM_PROMPT},
+    {"role": "user", "content": f"Query: {query}\nSchema: {json.dumps(schema)}"},
+]
+
+prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
+outputs = model.generate(
+    **inputs,
+    max_length=512,
+    temperature=0.1,
+    top_p=0.9,
+    num_return_sequences=1,
+)
+
+response = tokenizer.decode(outputs[0], skip_special_tokens=True)
+```
 
 ## Training Details
 
-### Training Data
-
-<!-- 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. -->
-
-[More Information Needed]
-
-### Training Procedure
-
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
-
-
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
-
-## Evaluation
-
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
-
-#### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
-
-### Results
-
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-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).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-[More Information Needed]
-
-### Compute Infrastructure
-
-[More Information Needed]
-
-#### Hardware
-
-[More Information Needed]
-
-#### Software
-
-[More Information Needed]
-
-## Citation [optional]
-
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
-
-**BibTeX:**
-
-[More Information Needed]
-
-**APA:**
-
-[More Information Needed]
-
-## Glossary [optional]
-
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
-
-[More Information Needed]
-
-## More Information [optional]
-
-[More Information Needed]
-
-## Model Card Authors [optional]
-
-[More Information Needed]
-
-## Model Card Contact
-
-[More Information Needed]
-### Framework versions
-
-- PEFT 0.14.0
+The model was trained on a NVIDIA H100 SXM using the following configuration:
+
+- Base Model: Qwen 2.5 7B
+- Training Method: LoRA
+- Quantization: 4-bit quantization using bitsandbytes
+- LoRA Configuration:
+  - Rank: 16
+  - Alpha: 32
+  - Dropout: 0.1
+  - Target Modules: Attention layers and MLP
+
+- Training Arguments:
+  - Epochs: 3
+  - Batch Size: 2
+  - Learning Rate: 5e-5
+  - Gradient Accumulation Steps: 8
+  - FP16 Training: Enabled
+  - Gradient Checkpointing: Enabled
+
+## Supported Query Types
+
+The model can handle various types of queries including:
+
+1. Simple text search:
+
+```json
+{
+    "term": "prosecco aperitif",
+    "limit": 5
+}
+```
+
+2. Numeric range queries:
+
+```json
+{
+    "term": "",
+    "where": {
+        "price": {
+            "between": [20, 100]
+        }
+    }
+}
+```
+
+3. Tag-based filtering:
+
+```json
+{
+    "term": "",
+    "where": {
+        "tags": {
+            "containsAll": ["red", "wine"]
+        }
+    }
+}
+```
+
+## Limitations
+
+- Does not support array of numbers or booleans
+- Maximum input length is 1024 tokens
+- Embedding fields are not supported in the schema
+
+## Citation
+
+If you use this model in your research, please cite:
+
+```
+@misc{query-translator-mini,
+  author = {OramaSearch Inc.},
+  title = {Query Translator Mini: Natural Language to Orama Query Translation},
+  year = {2024},
+  publisher = {HuggingFace},
+  journal = {HuggingFace Repository},
+  howpublished = {\url{https://huggingface.co/OramaSearch/query-translator-mini}}
+}
+```
+
+## License
+
+AGPLv3
+
+## Acknowledgments
+
+This model builds upon the Qwen 2.5 7B model and uses techniques from the PEFT library. Special thanks to the teams behind these projects.