lakun 0.1.0__tar.gz

lakun-0.1.0/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

lakun-0.1.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE
+include README.md README.zh-CN.md PYPI_README.md START.md
+include main.py train_lakun.py predict_lakun.py requirements-train.txt
+recursive-include examples *.json
+recursive-include lakun *.py LICENSE
+prune dataset
+prune images
+prune runs
+prune weights
+prune offline_wheels

lakun-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: lakun
+Version: 0.1.0
+Summary: Typed decisions from text or one image with LaKun
+Author: AI Discussion Room
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: lakun/vendor/laya/LICENSE
+Requires-Dist: torch>=2.6
+Requires-Dist: transformers<5,>=4.57
+Requires-Dist: accelerate<2,>=0.26
+Requires-Dist: safetensors>=0.4
+Requires-Dist: huggingface-hub>=0.20
+Requires-Dist: Pillow>=10
+Requires-Dist: numpy>=1.24
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# LaKun：文本与单图的类型化决策模型
+
+我做 LaKun，是为了让模型针对一段文本状态或一张图片，直接回答我指定的选择、档位评分和二元判断问题。它输出每个候选项的 softmax 分数与最高分选项，不生成自由文本。一次调用最多可提交 20 道问题，目前每次最多处理一张图片。
+
+这个 PyPI 安装包提供推理代码，源码包另含训练脚本；两种发行文件都**不包含权重或数据集**。我的完整检查点有 756,409,158 个参数；`lakun.safetensors` 大小为 3,025,715,432 字节（2.82 GiB），完整推理目录约 2.85 GiB。`0.7B` 是模型仓库名中的近似称呼。
+
+## 安装与使用
+
+先安装适合本机的 PyTorch，再安装 LaKun：
+
+```bash
+python -m pip install lakun
+```
+
+我目前还没有公开模型权重。只有已经取得**完整本地检查点目录**的人才能运行推理；安装代码包不会下载权重，`--checkpoint` 也不接受魔塔仓库 ID。我的源码项目中，检查点目录是 `runs/lakun_full/best`。在该目录存在的项目根目录下运行下面的命令，就能交互输入一道题、文本状态或本地图片路径：
+
+```bash
+lakun --checkpoint runs/lakun_full/best
+```
+
+纯文本单题也可以直接传参：
+
+```bash
+lakun --checkpoint runs/lakun_full/best --state "订单已经退款。" --type noul --question "订单是否已经退款？"
+```
+
+在交互模式下，输入图片路径即可问单图问题；选择题的候选项用 `|` 分隔。需要在脚本中使用时：
+
+```python
+from lakun import LaKunPredictor
+
+model = LaKunPredictor.from_pretrained("runs/lakun_full/best")
+result = model.predict(
+    [{"type": "choice", "question": "这是什么类型的请求？", "criteria": ["咨询", "投诉", "退款"]}],
+    state="用户说：我被重复扣费了，请尽快退款。",
+)
+print(result["answers"][0])
+```
+
+`choice` 接受 2–20 个候选项，`score` 接受 3–20 个有序档位，`noul` 固定为 `false/true`。`predicted_index` 从 0 开始。上下文最多 512 token；输入超限时，我的实现优先保留问题和候选项，再保留状态开头。这里的 softmax 分数未经概率校准，不能直接当成现实中的正确率。
+
+## 我测到的表现
+
+在按组隔离的测试集上，所选检查点与 `qwen3.8-flash` 生成的伪标签的一致率为：选择题 **83.11%**、评分题 **83.37%**、二元题 **80.92%**，共 12,703 组、38,141 题。这不是人工核验的通用准确率。我以验证损失选出第 16,882 步检查点；第二轮训练损失继续下降、验证损失反而上升，所以没有保留更晚的权重。
+
+我在 Windows 11、RTX 3060 12GB、PyTorch 2.7.1+cu126、FP32 下，先预热 5 次，再串行测 30 次 `predict()`：纯文本单题中位耗时 **17.01 ms**，单图单题 **162.01 ms**。计时包含分词、图片预处理（如适用）、前向传播和结果整理，不含权重加载、下载和网络耗时；其他硬件的速度可能不同。
+
+## 我目前看到的局限
+
+在接近我的训练数据分布的题目上，LaKun 已有可用表现；我观察到带明确数值线索或候选项间简单推理的任务比较容易答好，但还没有独立分项测评来证明这一点。外部垃圾评论分类实验显示跨领域迁移较弱；第二轮验证损失变差也让我警惕过度专用化，甚至可能存在微调坍塌，但尚不能证明底座能力已经丧失。数据伪标签、答案位置偏斜、单图限制及未经校准的分数，都需要谨慎对待。
+
+源码采用 Apache-2.0。**模型权重的许可尚未确定，也尚未公开**；源码许可不等于权重许可。我的 GitHub 源码仓库和魔塔权重仓库目前都是私有的。

lakun-0.1.0/PYPI_README.md

@@ -0,0 +1,52 @@
+# LaKun：文本与单图的类型化决策模型
+
+我做 LaKun，是为了让模型针对一段文本状态或一张图片，直接回答我指定的选择、档位评分和二元判断问题。它输出每个候选项的 softmax 分数与最高分选项，不生成自由文本。一次调用最多可提交 20 道问题，目前每次最多处理一张图片。
+
+这个 PyPI 安装包提供推理代码，源码包另含训练脚本；两种发行文件都**不包含权重或数据集**。我的完整检查点有 756,409,158 个参数；`lakun.safetensors` 大小为 3,025,715,432 字节（2.82 GiB），完整推理目录约 2.85 GiB。`0.7B` 是模型仓库名中的近似称呼。
+
+## 安装与使用
+
+先安装适合本机的 PyTorch，再安装 LaKun：
+
+```bash
+python -m pip install lakun
+```
+
+我目前还没有公开模型权重。只有已经取得**完整本地检查点目录**的人才能运行推理；安装代码包不会下载权重，`--checkpoint` 也不接受魔塔仓库 ID。我的源码项目中，检查点目录是 `runs/lakun_full/best`。在该目录存在的项目根目录下运行下面的命令，就能交互输入一道题、文本状态或本地图片路径：
+
+```bash
+lakun --checkpoint runs/lakun_full/best
+```
+
+纯文本单题也可以直接传参：
+
+```bash
+lakun --checkpoint runs/lakun_full/best --state "订单已经退款。" --type noul --question "订单是否已经退款？"
+```
+
+在交互模式下，输入图片路径即可问单图问题；选择题的候选项用 `|` 分隔。需要在脚本中使用时：
+
+```python
+from lakun import LaKunPredictor
+
+model = LaKunPredictor.from_pretrained("runs/lakun_full/best")
+result = model.predict(
+    [{"type": "choice", "question": "这是什么类型的请求？", "criteria": ["咨询", "投诉", "退款"]}],
+    state="用户说：我被重复扣费了，请尽快退款。",
+)
+print(result["answers"][0])
+```
+
+`choice` 接受 2–20 个候选项，`score` 接受 3–20 个有序档位，`noul` 固定为 `false/true`。`predicted_index` 从 0 开始。上下文最多 512 token；输入超限时，我的实现优先保留问题和候选项，再保留状态开头。这里的 softmax 分数未经概率校准，不能直接当成现实中的正确率。
+
+## 我测到的表现
+
+在按组隔离的测试集上，所选检查点与 `qwen3.8-flash` 生成的伪标签的一致率为：选择题 **83.11%**、评分题 **83.37%**、二元题 **80.92%**，共 12,703 组、38,141 题。这不是人工核验的通用准确率。我以验证损失选出第 16,882 步检查点；第二轮训练损失继续下降、验证损失反而上升，所以没有保留更晚的权重。
+
+我在 Windows 11、RTX 3060 12GB、PyTorch 2.7.1+cu126、FP32 下，先预热 5 次，再串行测 30 次 `predict()`：纯文本单题中位耗时 **17.01 ms**，单图单题 **162.01 ms**。计时包含分词、图片预处理（如适用）、前向传播和结果整理，不含权重加载、下载和网络耗时；其他硬件的速度可能不同。
+
+## 我目前看到的局限
+
+在接近我的训练数据分布的题目上，LaKun 已有可用表现；我观察到带明确数值线索或候选项间简单推理的任务比较容易答好，但还没有独立分项测评来证明这一点。外部垃圾评论分类实验显示跨领域迁移较弱；第二轮验证损失变差也让我警惕过度专用化，甚至可能存在微调坍塌，但尚不能证明底座能力已经丧失。数据伪标签、答案位置偏斜、单图限制及未经校准的分数，都需要谨慎对待。
+
+源码采用 Apache-2.0。**模型权重的许可尚未确定，也尚未公开**；源码许可不等于权重许可。我的 GitHub 源码仓库和魔塔权重仓库目前都是私有的。

lakun-0.1.0/README.md

@@ -0,0 +1,131 @@
+# LaKun: typed decisions from text or one image
+
+English · [简体中文](README.zh-CN.md) · [Dataset profile and charts](analysis/DATASET_PROFILE.md)
+
+I built LaKun to answer questions I define in advance about a text state or a single image: choose among options, select an ordered rating bin, or decide `false/true`. It returns softmax scores and the highest-scoring option for each question. It does not generate free-form text and is not a chat model. One `predict()` call can contain all three question types, with up to 20 questions and one image.
+
+> **Release status:** I distribute the code package on PyPI. My [GitHub source repository](https://github.com/AI-Discussion-Room/LaKun) and [ModelScope weight repository](https://modelscope.cn/models/hh108801/LaKun-0.7B) remain **private**. The code is Apache-2.0; the weight license is **not yet decided** and must not be inferred from the code license. Installing the package alone does not provide a checkpoint.
+
+## At a glance
+
+| Item | Current implementation / measurement |
+|---|---|
+| Input | A text state or one image, with 1–20 typed questions |
+| Questions | `choice`: 2–20 options; `score`: 3–20 bins; `noul`: `false/true` |
+| Output | Per-question `criteria`, `probabilities`, and `predicted_index`; probability calibration is **not validated** |
+| Architecture | mmBERT-base + SigLIP SO400M + visual-token bridge + typed decision head |
+| Parameter count | **756,409,158 (~0.756B)** across 627 checkpoint tensors; `0.7B` is an approximate repository name |
+| Weight size | `lakun.safetensors`: **3,025,715,432 bytes (2.82 GiB)**; complete inference directory: about **2.85 GiB** |
+| Context | At most 512 tokens, reserving 64 visual tokens for images; overlength inputs are truncated, prioritizing question/options and the start of the state |
+
+I jointly fine-tuned the text and vision encoders. I did **not** load a Laya fine-tuned checkpoint; the decision head uses Laya-derived code with its notice preserved. LaKun's results are not Laya's results.
+
+## Quick start
+
+Install a PyTorch build appropriate for your machine first. Install my code package from PyPI:
+
+```bash
+python -m pip install lakun
+```
+
+If you have access to my source checkout, you can instead run these commands from the project root:
+
+```bash
+python -m pip install -e .
+python predict_lakun.py --checkpoint runs/lakun_full/best --input examples/text_input.json
+```
+
+For **one question at a time**, run `python main.py --checkpoint runs/lakun_full/best` and enter a text state (or image path), question type, question, and options at the prompts. You can also use a non-interactive command:
+
+```bash
+python main.py --checkpoint runs/lakun_full/best --state "The order has been refunded." --type noul --question "Has the order been refunded?"
+# One-image example: replace photo.jpg with your local image path
+python main.py --checkpoint runs/lakun_full/best --image photo.jpg --type choice --question "What is shown?" --criteria cat dog car
+```
+
+The command prints the top option and all softmax scores. After a PyPI installation, use `lakun --checkpoint runs/lakun_full/best` for the same interactive interface when running from my project root with its private checkpoint present.
+
+`runs/lakun_full/best/` is my local complete checkpoint, not part of the Git repository. If you have access to the private ModelScope repository, download it first and pass the resulting local directory to `--checkpoint`; the loader does **not** accept a repository ID directly.
+
+Here is the real API with all three question types in one request. Supply `state=` for text, or `image="/path/to/image.jpg"` for one local image:
+
+```python
+from lakun import LaKunPredictor
+
+model = LaKunPredictor.from_pretrained("runs/lakun_full/best")
+result = model.predict(
+    [
+        {"type": "choice", "question": "What kind of request is this?", "criteria": ["question", "complaint", "refund"]},
+        {"type": "score", "question": "How urgent is it?", "criteria": ["low", "medium", "high"]},
+        {"type": "noul", "question": "Does the user request a refund?", "criteria": ["false", "true"]},
+    ],
+    state="The customer says they were charged twice and asks for a prompt refund.",
+)
+for answer in result["answers"]:
+    print(answer["type"], answer["predicted_index"], answer["probabilities"])
+```
+
+`predicted_index` is zero-based and refers to the supplied option order. For `score`, it is the winning **bin index**, not a continuous regression output. The probabilities are softmax values, not calibrated real-world correctness probabilities.
+
+For overlength inputs, the encoder keeps the question and options first (shortening very long options if necessary), then as much of the **beginning of the state** as fits. Discarded trailing text is not considered. Summarize or split long documents if the important evidence appears near the end.
+
+## What I measured
+
+I split groups—not individual questions—between training, validation and test. I selected the checkpoint at optimizer step **16,882** using validation loss. On **12,703 held-out groups / 38,141 questions**, agreement with the teacher's pseudo-labels was:
+
+| Type | Agreement |
+|---|---:|
+| Choice | 83.11% |
+| Score | 83.37% |
+| Noul | 80.92% |
+
+The labels were generated by `qwen3.8-flash`, not verified by people. These are **not** general-purpose accuracy, reasoning, or probability-calibration scores. Best validation loss was `0.014464`. During the second epoch, training loss kept falling while validation loss rose, so I retained the earlier checkpoint and stopped training.
+
+### Local inference speed
+
+I measured the complete `LaKunPredictor.predict()` call on **Windows 11**, an **NVIDIA GeForce RTX 3060 12GB**, **PyTorch 2.7.1+cu126**, using FP32 inference. For each scenario I ran 5 warm-ups and 30 sequential timed calls, synchronizing CUDA before and after timing. The measurement includes tokenization, image decoding/preprocessing where applicable, forward pass, and result construction. It **excludes** checkpoint loading, download, and network overhead. The image is one local held-out sample; this is a speed test, not an accuracy test.
+
+| Scenario | Questions/call | Median | p95 |
+|---|---:|---:|---:|
+| Text | 1 | 17.01 ms | 19.23 ms |
+| Text | 3 | 18.18 ms | 18.65 ms |
+| One image | 1 | 162.01 ms | 168.69 ms |
+| One image | 3 | 168.71 ms | 171.59 ms |
+
+I include both the [benchmark script](analysis/benchmark_inference.py) and the [measurement record](analysis/benchmark_rtx3060_2026-09-24.json). To rerun: `python -m analysis.benchmark_inference --checkpoint runs/lakun_full/best --image /path/to/one-image.jpg`. These results should not be presented as RTX 4090 throughput or concurrent serving latency.
+
+## My dataset
+
+I unified images and text into **one state + multiple typed questions** per group. All question labels were generated by `qwen3.8-flash`. The current profile contains **126,663 groups / 380,424 questions**: 59,996 image groups / 180,424 questions and 66,667 text groups / 200,000 questions. Choice, score and noul occur at similar frequencies. The approximately 8:1:1 split keeps every group's questions together.
+
+![Dataset size, question types and splits](analysis/figures/01-overview.png)
+
+The profile also covers option counts, rating bins, seven image source subsets and 50 synthetic text topics. One important bias: among four-option questions, option B is the teacher's answer in **53.15%** of image questions and **46.48%** of text questions; D is only **1.74%** and **2.98%**, respectively. The model may exploit answer position rather than content.
+
+![Option and pseudo-label distributions](analysis/figures/02-options-and-labels.png)
+
+[Source and coverage chart](analysis/figures/03-coverage.png) · [All 50 text topics and answer positions](analysis/figures/04-domains-and-choice-labels.png) · [Full dataset profile](analysis/DATASET_PROFILE.md). The chart labels are currently Chinese.
+
+I have not uploaded the raw JSONL, images, or the 1,000 inspected test examples to GitHub or ModelScope. These charts contain aggregates only. Upstream image/data terms need further review before any dataset release.
+
+## Training and reproducibility
+
+`train_lakun.py` needs Python 3.10+, a CUDA-enabled PyTorch build, `requirements-train.txt`, the original base weights under `weights/mmbert-base/` and `weights/siglip-so400m-patch14-384/`, plus six `dataset/{image,text}_{train,val,test}.jsonl` files and their referenced images. I recommend a small pipeline run before full training:
+
+```bash
+python -m pip install -r requirements-train.txt
+python train_lakun.py --train-groups 12 --val-groups 6 --test-groups 6 --epochs 1 --out runs/lakun_pilot
+python train_lakun.py
+```
+
+The script uses visible local GPUs (DDP with multiple GPUs), checks validation every 3,000 optimizer steps, runs at most three epochs, and stops after three checks without sufficient loss improvement. The complete `best/` directory contains both encoders and the custom decision components; do not download just the `.safetensors` file. Current checkpoints omit optimizer state and cannot resume the precise interrupted training step. See [`START.md`](START.md).
+
+## Release boundaries
+
+I keep code in [`AI-Discussion-Room/LaKun`](https://github.com/AI-Discussion-Room/LaKun) and weights in [`hh108801/LaKun-0.7B`](https://modelscope.cn/models/hh108801/LaKun-0.7B); both repositories are private at present. I distribute the code package through PyPI, without weights or data; see my [release checklist](RELEASE_PYPI.md). A `pip install lakun` installation still needs a complete checkpoint obtained separately. Transformers `AutoModel.from_pretrained()` cannot load this custom architecture directly. The source is [Apache-2.0](LICENSE); before a public weight release I still need to review upstream model/data terms and decide on a separate weight license.
+
+## Limitations I am seeing
+
+Within a distribution close to my training data, LaKun is already useful for these typed decisions. In informal use, I find questions with explicit numerical cues or simple inference between supplied options easier for it, **but I have not run a separate controlled benchmark for that observation**. An external spam-classification experiment exposed weak cross-domain transfer. Falling training loss alongside worse validation loss also makes me concerned about over-specialization or a form of “fine-tuning collapse.” I cannot yet prove that the pretrained backbone itself has lost capability; that needs comparisons with the unfine-tuned base, other checkpoints, and human-labeled out-of-domain tests.
+
+I therefore do not claim this is a general classifier, a strongly generalizing vision model, or a verified numerical-reasoning model. One-image input, answer-position bias, pseudo-label error, uncalibrated scores, cross-domain behavior, and data provenance remain open limitations.

lakun-0.1.0/README.zh-CN.md

@@ -0,0 +1,131 @@
+# LaKun：让文字或单张图片回答类型化问题
+
+[English](README.md) · 简体中文 · [数据集完整统计](analysis/DATASET_PROFILE.md)
+
+我做 LaKun，是想让模型面对一段状态或一张图片时，直接回答我预先定义的问题：从候选项中选择、按档位评分，或者回答 `false/true`。它输出每个候选项的 softmax 分数和最高分选项，不生成自由文本，也不是聊天模型。一次 `predict()` 可以同时提交这三类问题；目前一个请求最多 20 题、最多一张图片。
+
+> **发布状态：**我通过 PyPI 分发代码包。源码位于私有 GitHub 仓库，完整权重位于私有魔塔仓库 [`hh108801/LaKun-0.7B`](https://modelscope.cn/models/hh108801/LaKun-0.7B)。代码采用 Apache-2.0；**权重的公开许可尚未确定**，我不会把源码许可自动等同于权重许可。只安装代码包不能完成推理。
+
+## 一眼看懂
+
+| 项目 | 当前实现与实测 |
+|---|---|
+| 输入 | 文本状态，或单张图片；每次 1–20 个类型化问题 |
+| 问题 | `choice` 2–20 个候选项；`score` 3–20 档；`noul` 固定 `false/true` |
+| 输出 | 每题的 `criteria`、`probabilities`、`predicted_index`；**概率尚未做校准验证** |
+| 模型 | mmBERT-base + SigLIP SO400M + 视觉 token 桥接 + 决策头 |
+| 参数量 | **756,409,158（约 0.756B）**，从本检查点 627 个张量逐项统计；`0.7B` 是仓库名中的近似称呼 |
+| 权重体积 | `lakun.safetensors` **3,025,715,432 字节（2.82 GiB）**；完整推理目录约 **2.85 GiB** |
+| 上下文 | 最多 512 token（图像预留 64 个视觉 token）；超限时自动截断，优先保留问题/候选项和状态开头 |
+
+我联合微调了文本和视觉编码器，没有使用 Laya 已训练好的权重。决策头借鉴并保留了 Laya 衍生代码及许可证；因此 LaKun 的指标不能当作 Laya 的指标。
+
+## 先跑起来
+
+先安装与本机驱动匹配的 PyTorch，再从 PyPI 安装我的代码包：
+
+```bash
+python -m pip install lakun
+```
+
+已有源码访问权限时，也可以在项目根目录改用以下命令：
+
+```bash
+python -m pip install -e .
+python predict_lakun.py --checkpoint runs/lakun_full/best --input examples/text_input.json
+```
+
+如果只想自己输入**一道题**，运行 `python main.py --checkpoint runs/lakun_full/best`，按提示填写文本状态（或一张图片的路径）、题型、问题和候选项。也可以不进入交互模式，直接给参数：
+
+```bash
+python main.py --checkpoint runs/lakun_full/best --state "订单已经退款。" --type noul --question "订单是否已经退款？"
+# 单图示例：把 photo.jpg 换成你自己的图片路径
+python main.py --checkpoint runs/lakun_full/best --image photo.jpg --type choice --question "图中是什么？" --criteria 猫 狗 汽车
+```
+
+输出会显示最高分候选项和所有候选项的 softmax 分数。通过 PyPI 安装后，在含有上述私有检查点的项目根目录下，也可以运行 `lakun --checkpoint runs/lakun_full/best` 进入相同的交互界面。
+
+`runs/lakun_full/best/` 是我本地的完整检查点目录，不在 GitHub 里。若你有私有魔塔仓库权限，也可以先下载到本地，再将下载目录传给 `--checkpoint`；当前加载器**不接受仓库 ID 代替本地路径**。
+
+下面是真实 API 的三题同问示例；`state` 在这里输入，图片任务则通过 `image=` 传一张本地图片：
+
+```python
+from lakun import LaKunPredictor
+
+model = LaKunPredictor.from_pretrained("runs/lakun_full/best")
+result = model.predict(
+    [
+        {"type": "choice", "question": "这是什么类型的请求？", "criteria": ["咨询", "投诉", "退款"]},
+        {"type": "score", "question": "这件事有多紧急？", "criteria": ["不紧急", "一般", "紧急"]},
+        {"type": "noul", "question": "用户是否要求退款？", "criteria": ["false", "true"]},
+    ],
+    state="用户说：我被重复扣费了，请尽快退款。",
+)
+for answer in result["answers"]:
+    print(answer["type"], answer["predicted_index"], answer["probabilities"])
+```
+
+`predicted_index` 从 0 开始，对应你传入的 `criteria` 顺序。`score` 目前返回**最高分档位的索引**，不是连续回归分数。这里的 `probabilities` 是候选项 softmax 值；我还没有做可靠的概率校准测试，不能把 `0.9` 理解为“现实中有 90% 的正确率”。
+
+输入过长时，编码器会优先保留问题与候选项（过长的选项也会按预算缩短），再保留**状态文本开头**能装下的部分；被截掉的尾部不会参与判断。如果关键信息在后面，建议先压缩文本或分段提问。
+
+## 我测到的效果
+
+我按组划分训练、验证和测试集；选模型时只看验证损失，最终保留优化步 **16,882** 的检查点。在 **12,703 组 / 38,141 题**的留出测试集上，它与教师伪标签的一致率为：
+
+| 类型 | 一致率 |
+|---|---:|
+| Choice | 83.11% |
+| Score | 83.37% |
+| Noul | 80.92% |
+
+这些标签由 `qwen3.8-flash` 生成，**不是人工真值**；这里的数字不是通用准确率，也不能证明数值推理或图片理解的真实能力。最佳验证损失为 `0.014464`；第二轮训练损失继续下降时，验证损失反而上升，所以我保留第一轮末的权重并早停。损失和上面三个一致率是不同指标，不能互相替代。
+
+### 本地推理速度
+
+我用本项目完整检查点在 **Windows 11、NVIDIA GeForce RTX 3060 12GB、PyTorch 2.7.1+cu126、FP32 推理** 下测量。每种场景先预热 5 次，再串行执行 30 次；每次计时前后同步 CUDA。计时覆盖 `predict()` 的分词、图片读取与预处理、前向传播和结果整理；**不含**模型加载、下载或网络传输。图片来自本地测试集中的一张样本，测速不是准确率评估。
+
+| 场景 | 每次问题数 | 中位延迟 | p95 延迟 |
+|---|---:|---:|---:|
+| 纯文本 | 1 | 17.01 ms | 19.23 ms |
+| 纯文本 | 3 | 18.18 ms | 18.65 ms |
+| 单张图片 | 1 | 162.01 ms | 168.69 ms |
+| 单张图片 | 3 | 168.71 ms | 171.59 ms |
+
+我把[可复测脚本](analysis/benchmark_inference.py)和[本次测量记录](analysis/benchmark_rtx3060_2026-09-24.json)都放在 `analysis/`。复测命令：`python -m analysis.benchmark_inference --checkpoint runs/lakun_full/best --image /path/to/one-image.jpg`。这组结果仅代表上述机器和输入，不等于 AutoDL 的 4090 速度，也不是多请求并发吞吐。
+
+## 我构建的数据集
+
+我将图像和文本统一成“**一组状态 + 多道类型化问题**”的格式，问题标签全部来自 `qwen3.8-flash`。当前统计有 **126,663 组 / 380,424 题**：图像 59,996 组 / 180,424 题，文本 66,667 组 / 200,000 题。三类题数量接近，按组约 8:1:1 划分，保证同组问题不会跨训练、验证、测试集。
+
+![数据规模、三类任务和划分](analysis/figures/01-overview.png)
+
+我在分析里还统计了候选项数量、评分档位、二元标签、7 个图像来源和 50 个文本方向。最值得警惕的是四选一的答案位置偏斜：图像题的 B 项占 **53.15%**、D 项仅 **1.74%**；文本题 B 项占 **46.48%**、D 项仅 **2.98%**。模型可能利用位置规律，而不是真正理解内容。
+
+![候选项和伪标签分布](analysis/figures/02-options-and-labels.png)
+
+[查看其余两张图：来源/覆盖](analysis/figures/03-coverage.png) · [50 个文本方向及位置分布](analysis/figures/04-domains-and-choice-labels.png) · [完整频数与统计方法](analysis/DATASET_PROFILE.md)
+
+我没有把训练 JSONL、图片或测试样本上传到 GitHub / 魔塔。图表是汇总统计，不包含那 1,000 组测试明细；原始图像来源和数据许可还需要逐项核对。
+
+## 训练与复现
+
+训练入口是 `train_lakun.py`。需要 Python 3.10+、可用的 CUDA PyTorch、`requirements-train.txt`、原始底座权重 `weights/mmbert-base/` 与 `weights/siglip-so400m-patch14-384/`，以及六份 `dataset/{image,text}_{train,val,test}.jsonl` 和图片。先做小样本流程检查，再开始全量训练：
+
+```bash
+python -m pip install -r requirements-train.txt
+python train_lakun.py --train-groups 12 --val-groups 6 --test-groups 6 --epochs 1 --out runs/lakun_pilot
+python train_lakun.py
+```
+
+训练默认使用本机可见 GPU（多卡为 DDP），每 3,000 优化步验证，最多 3 轮，连续 3 次验证损失未达到改进阈值则早停。检查点包含两座编码器和自定义决策模块；推理时要保留整个 `best/` 目录，不能只拿 `.safetensors`。当前检查点没有优化器状态，不能无损接着上次中断的优化步训练。详见 [`START.md`](START.md)。
+
+## 发布边界
+
+我把代码放在 [`AI-Discussion-Room/LaKun`](https://github.com/AI-Discussion-Room/LaKun)，把权重放在 [`hh108801/LaKun-0.7B`](https://modelscope.cn/models/hh108801/LaKun-0.7B)；两处仓库目前均为**私有**。我通过 PyPI 分发不含权重与数据的代码包，详见[发布清单](RELEASE_PYPI.md)。即使 `pip install lakun` 成功，仍需另外取得完整权重。这个自定义架构也不能直接通过 Transformers `AutoModel.from_pretrained()` 加载。源码采用 [Apache-2.0](LICENSE)；权重公开前，我还需要完成上游模型/数据条款和权重许可检查。
+
+## 我目前看到的局限
+
+我把局限放在最后，也会在魔塔模型卡保留同样说明。LaKun 在**与训练数据接近的分布**上，对这三种类型化题目已有可用表现；我尤其觉得有明确数值线索、需要在候选项之间做简单推理的题目更容易答好，**但这只是目前试用观察，尚无独立分项测评支持**。另一方面，外部垃圾评论分类试验暴露出明显的跨领域迁移问题；第二轮训练损失下降而验证损失变差，也让我警惕过度专用化，甚至某种“微调坍塌”现象。现在还不能证明是底座能力真正坍塌，需要与未微调底座、不同检查点及人工标注域外集做对照。
+
+因此我不会宣称它已经是通用分类器、强泛化视觉模型或可靠的数值推理模型。它目前只支持单张图片；答案位置偏斜、伪标签误差、未经校准的概率、跨域表现和来源许可，都是公开前要继续解决的问题。

lakun-0.1.0/START.md

@@ -0,0 +1,48 @@
+# LaKun 启动说明
+
+LaKun 使用原始 mmBERT-base 文本权重、原始 SigLIP SO400M 图像权重，以及受 Laya 启发的决策评分头；不加载 Laya 微调权重。项目包名是 `lakun`。
+
+## 放到服务器并训练
+
+保留 `lakun/`、`train_lakun.py`、`predict_lakun.py`、`pyproject.toml`、`requirements-train.txt`、`tokenizer/`、`images/`、`dataset/` 中图文各三份 `*_train.jsonl`／`*_val.jsonl`／`*_test.jsonl`，以及 `weights/mmbert-base/` 与 `weights/siglip-so400m-patch14-384/` 中的正式权重及配置。划分按图片／文本 group ID 完成，比例约 8:1:1，同组问题不跨集合。图片路径由数据行引用，必须保留所引用图片及相对目录结构。
+
+在项目根目录运行：
+
+```bash
+python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.device_count()); assert torch.cuda.is_available()"
+python -m pip install -r requirements-train.txt
+python train_lakun.py --train-groups 12 --val-groups 6 --test-groups 6 --epochs 1 --out runs/lakun_pilot
+python train_lakun.py
+```
+
+第一行确认当前 `python` 指向带 CUDA 的 PyTorch 环境，第二行安装本目录的 LaKun 包和其他依赖；如果环境中已有满足要求的 PyTorch，就不需要另行安装。第三行是小样本真权重试跑，确认显存与速度；第四行是完整训练。默认最多 3 轮，每 3000 个优化步验证一次，并在每轮结束时验证；验证损失改善至少 0.001 才更新最佳权重，连续 3 次无改善就早停。可用 `--epochs`、`--eval-every`、`--patience`、`--min-delta` 调整。训练期间不看测试集，最后只对最佳权重测一次。`train_lakun.py` 自动使用当前机器可见的全部 GPU，单卡直接运行，多卡自动使用 DDP；卡数不写死。只用部分 GPU 时设置 `CUDA_VISIBLE_DEVICES`。正式训练采用 BF16；不要把分散在不同服务器上的 GPU 当作同一台机器的多卡。
+
+## 权重保存与下载
+
+全量训练默认写入服务器项目目录 `runs/lakun_full/`，其中最佳完整模型权重在 `runs/lakun_full/best/`。当前设置单文件上限 10GB，正常会得到一个 `best/lakun.safetensors`；`best/` 内还含文本／图像配置、tokenizer、图像预处理器及模型卡。训练报告 `report.json` 和验证轨迹 `validation_history.json` 在上级目录。训练结束后，推理至少需要下载**整个 `runs/lakun_full/best/` 文件夹**，不要只下载某个 `.safetensors`；如需保留训练记录，再下载同级的 `report.json` 和 `validation_history.json`。小样本试跑输出在 `runs/lakun_pilot/`，不是正式模型。可以用 `--out` 指定其他输出目录。最佳检查点是包括两座编码器和决策头的完整权重，推理不再需要额外读取原始两份底座；原始底座建议留下作重新训练与复现实验。
+
+目前保存的是最佳模型的完整推理权重，不含优化器状态；如果训练中断，最佳权重可以推理，但当前脚本不能从中断位置无损续训。重新启动默认从两份原始底座开始，务必使用新的 `--out`，避免覆盖之前的最佳权重。
+
+载入正式检查点做一次测试：
+
+```bash
+python predict_lakun.py --checkpoint runs/lakun_full/best --input examples/text_input.json
+python predict_lakun.py --checkpoint runs/lakun_full/best --modality image --group-index 0
+```
+
+第一条使用仓库内的纯文本输入示例，不需要本地测试集；第二条读取本地测试集与图片。若做自己的图片推理，可在输入 JSON 中添加 `image` 路径。
+
+在自己的代码中推理：
+
+```python
+from lakun import LaKunPredictor
+
+model = LaKunPredictor.from_pretrained("runs/lakun_full/best")
+result = model.predict(
+    [{"type": "choice", "question": "图中是什么？", "criteria": ["猫", "狗", "汽车"]}],
+    image="/path/to/your/image.jpg",
+)
+print(result["answers"])
+```
+
+发布到魔塔或 Hugging Face 时，上传 `runs/lakun_full/best/` 的**全部内容**到模型仓库根目录，并让用户安装 `lakun` 代码；本项目的自定义融合层不能只靠两个原始底座权重推理。GitHub 代码仓库不含权重或数据。当前推理接口接受本地检查点目录或 Hugging Face 仓库 ID；魔塔仓库须先下载到本地目录再加载。Laya 派生源码位于 `lakun/vendor/laya/`，请保留该目录的 Apache-2.0 许可证与署名。模型权重的发布许可证需另行确定，原始底座的模型卡和许可也应在发布前核对。当前测试指标基于教师伪标签，不等于人工验证效果。