Update README.md

README.md

@@ -8,197 +8,143 @@ base_model:
 - naver-hyperclovax/HyperCLOVAX-SEED-Think-14B
 ---
 
-# Model Card for Model ID
+Of course. Here is the model card rewritten in natural, professional English.
 
-<!-- Provide a quick summary of what the model is/does. -->
+-----
 
+## **Model Card — HyperCLOVAX-SEED-Think-14B (fork) + DeepConf**
 
+### **Summary**
 
-## Model Details
+This model enhances a user-forked version of **HyperCLOVAX-SEED-Think-14B** by integrating ideas from Meta AI × UCSD's **DeepConf**. It performs confidence-based quality estimation and adaptive sampling to improve both accuracy and efficiency.
 
-### Model Description
+The core of this method is the **Lowest Group Confidence (LGC)**, a metric that uses a sliding window to identify the "most uncertain segment" of a generation path. This allows for intelligent offline filtering (**Top-p% Filtering**, **Confidence-Weighted Voting**) and online optimization (**Early Abort**), ultimately achieving higher accuracy at a lower computational cost.
 
-<!-- Provide a longer summary of what this model is. -->
+-----
 
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
+### **1. Background and Motivation**
 
-- **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]
+While **Self-Consistency**—generating multiple paths and taking a majority vote—can improve performance on reasoning tasks, its practical application is limited by prohibitive computational costs and the noise introduced by low-quality generation paths.
 
-### Model Sources [optional]
+The **DeepConf** framework addresses this by reading the model's internal **token generation probability distribution (confidence)** to estimate the quality of a path in real time. Simple average confidence can be misleading due to the "pitfall of averages." We instead use the sliding-window LGC metric to quantify the path's weakest link.
 
-<!-- Provide the basic links for the model. -->
+-----
 
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+### **2. Methods**
 
-## Uses
+#### **2.1 Confidence Metric: Lowest Group Confidence (LGC)**
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+LGC is calculated by moving a window of size $W$ (e.g., 2048 tokens) across the entire generation path, calculating the average confidence within each window, and taking the minimum value as the quality score for the entire trajectory.
 
-### Direct Use
+  * **Intuition**: The quality of a path is limited by its most uncertain or speculative segment.
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+The formula is:
+$$\text{LGC}(\text{trajectory}) = \min_{t} \frac{1}{W}\sum_{i=t}^{t+W-1} \text{conf}(y_i)$$
 
-[More Information Needed]
+Here, $\\text{conf}(y\_i)$ is the generation probability of token $y\_i$. Our implementation defaults to using the softmax probability of the top-1 token.
 
-### Downstream Use [optional]
+#### **2.2 Offline Methods: Top-p% Filtering & Confidence-Weighted Voting**
 
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+  * **Top-p% Filtering**: Among $N$ generated paths, only the **top p%** with the highest confidence scores are included in the final vote.
+  * **Confidence-Weighted Voting**: Each path's vote is weighted by a function of its confidence score (e.g., its LGC score or a monotonic transformation of it).
+  * **Literature Example**: For a GPT-family model on AIME-2025, using only the top 10% of 512 samples reportedly improved accuracy from 97.0% to 99.9%. (Note: This is a literature example; this model's specific results are detailed below.)
 
-[More Information Needed]
+#### **2.3 Online Method: Adaptive Sampling (Early Abort)**
 
-### Out-of-Scope Use
+1.  **Warm-up**: Fully generate $M$ initial paths (e.g., 16) to establish a dynamic confidence threshold, $\\tau$.
+2.  **Monitoring**: For each new path, if its real-time LGC drops below $\\tau$ at any point, the generation is immediately aborted and discarded, preventing wasted computation on low-quality paths.
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+<!-- end list -->
 
-[More Information Needed]
+  * **Reported Gains**: This technique can reduce the number of sampled tokens by \~85% while maintaining or even improving accuracy.
 
-## Bias, Risks, and Limitations
+#### **2.4 HyperCLOVAX (Think/Answer) Specialization**
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+We leverage the model's ChatML structure, which separates the `thinking` (exploration) and `answer` (formal response) stages, by applying a dual-threshold system: $\\tau\_{\\text{think}} \< \\tau\_{\\text{answer}}$.
 
-[More Information Needed]
+  * **Thinking Stage**: A looser threshold encourages broader exploration of ideas.
+  * **Answer Stage**: A stricter threshold enforces high confidence, ensuring formal correctness and accuracy in the final output.
 
-### Recommendations
+-----
 
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+### **3. Hyperparameters (Recommended Defaults)**
 
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+| Name                | Description                                        | Default Value (Example)                  |
+| ------------------- | -------------------------------------------------- | ---------------------------------------- |
+| `W`                 | Sliding window length (tokens)                     | 2048                                     |
+| `p`                 | Percentage for Top-p% Filtering                  | 10                                       |
+| `M`                 | Number of warm-up paths for calibration          | 16                                       |
+| $\\tau\_{\\text{think}}$ | Early abort threshold for the `thinking` stage     | Dynamic (based on warm-up)               |
+| $\\tau\_{\\text{answer}}$  | Early abort threshold for the `answer` stage       | Dynamic (based on warm-up, stricter)     |
+| `N_max`             | Max number of paths to sample (online)             | Optional limit (e.g., 64)                |
 
-## How to Get Started with the Model
+-----
 
-Use the code below to get started with the model.
+### **4. Evaluation**
 
-[More Information Needed]
+#### **4.1 AIME 2025 (30-question slice) — `deepconf` vs. `original`**
 
-## Training Details
+*Scoring: Correct = 1, Incorrect / No Format = 0. "No Format" is treated as not attempted.*
 
-### Training Data
+| Metric                  | `original` | `deepconf` | Notes                                         |
+| ----------------------- | ---------- | ---------- | --------------------------------------------- |
+| **Total Correct** | 8          | **10** | +2 questions correct                          |
+| **Accuracy (out of 30)** | 26.7%      | **33.3%** | +6.7%p improvement                            |
+| Attempts (Format OK)    | 8          | 11         | `deepconf` attempted 3 more questions         |
+| Format Failures         | 22         | 19         | `deepconf` shows better format stability      |
+| **Head-to-Head** | —          | —          | **2 Wins / 0 Losses / 28 Ties for `deepconf`** |
 
-<!-- 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. -->
+**Breakdown by Part:**
 
-[More Information Needed]
+  * **Part I**: Both models solved 6/15 questions (Tie).
+  * **Part II**: `original` solved 2/15, while `deepconf` solved 4/15. **The performance gain was concentrated in the more difficult second half.**
 
-### Training Procedure
+*Note: The high number of "Format Failures" in this slice indicates that the ability to adhere to strict output formatting was a significant factor in the final score.*
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+#### **4.2 Efficiency & Speed (10-question sample test)**
 
-#### Preprocessing [optional]
+| Metric                    | Improvement with `deepconf` |
+| ------------------------- | ---------------------------- |
+| **Majority-Vote Accuracy** | +20.0%p                      |
+| **Avg. Generated Tokens** | –29.6%                       |
+| **Avg. Generation Time** | –41.6%                       |
 
-[More Information Needed]
+***Caution: These results are based on a very small sample size (N≈10).*** However, they signal a meaningful improvement across accuracy, speed, and cost.
 
+-----
 
-#### Training Hyperparameters
+### **5. Use Cases and Recommended Pipeline**
 
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
+This model is ideal for **mathematical and logical reasoning tasks** where it offers significant sample savings and improved reliability compared to standard self-consistency.
 
-#### Speeds, Sizes, Times [optional]
+**Recommended Pipeline:**
 
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
+1.  **Online**: Use adaptive sampling with a warm-up phase and early abort to filter out low-quality paths efficiently.
+2.  **Offline**: Apply Top-p% Filtering (with `p=10` as a starting point) to the remaining high-quality paths.
+3.  **Finalization**: Use Confidence-Weighted Voting on the filtered set and apply a final format validation step to extract the answer.
 
-[More Information Needed]
+-----
 
-## Evaluation
+### **6. Limitations & What to Watch Out For**
 
-<!-- This section describes the evaluation protocols and provides the results. -->
+  * **Confidence Miscalibration**: If the model's probability estimates are not well-calibrated, the threshold $\\tau$ may be unreliable. This can be mitigated by tuning temperature/top-k or relying on warm-up statistics.
+  * **Domain Shift**: The optimal hyperparameters ($\\tau, W, p$) may need recalibration when applied to new domains or problem styles.
+  * **Unintended Early Aborts**: A path might be discarded prematurely if it contains rare tokens or formatting that cause a temporary dip in confidence. Consider implementing a minimum generation length or a cooldown period.
+  * **Reliance on Format Validation**: If the final answer extraction logic is not robust, "correct but badly formatted" answers may still be missed.
 
-### Testing Data, Factors & Metrics
+-----
 
-#### Testing Data
+### **7. Responsible Use**
 
-<!-- This should link to a Dataset Card if possible. -->
+  * **Expose Reasoning**: For math and coding tasks, always pair the final answer with the generation's reasoning or verification steps to mitigate hallucinations and minor errors.
+  * **Resource Allocation**: While early abort reduces overall cost, the warm-up phase introduces overhead. Manage this effectively with batching and queueing in a production environment.
+  * **Bias and Fairness**: Confidence-based filtering may systematically favor certain response styles. We recommend periodic auditing and sampling to ensure fairness and diversity in outputs.
 
-[More Information Needed]
+-----
 
-#### Factors
+### **Citation**
 
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+  * **Original Idea**: Fu, Wang, Tian, Zhao et al., *DeepConf: A Confidence-based Framework for LLM-based Code Generation* (Meta AI × UCSD).
+  * **This Work**: A report on the integration of DeepConf with a forked HyperCLOVAX-SEED-Think-14B, including the application of ChatML-aware dual thresholds.
 
-[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]
+*Feel free to ask for configuration templates for different profiles (e.g., **accuracy-focused**, **cost-sensitive**, **balanced**) with tuned values for **p, W, M, and τ**.*