SubText

LLM-Based Steganography Framework
基于大语言模型概率分布的隐秘信息传输框架

📚 目录 (Table of Contents)

• 📖 项目简介 (Introduction)
• ✨ 核心特性 (Features)
• 🛠️ 安装指南 (Installation)
• 🚀 服务部署 (Service Deployment)
• 🔌 API 接口 (API Usage)
• 💻 Web 前端 (Web Frontend)
• ⚠️ 免责声明 (Disclaimer)
• 📄 开源协议 (License)

📖 项目简介 (Introduction)

SubText 是一个利用大语言模型（LLM）的概率分布特性进行隐秘信息传输的框架。与传统的文本隐写不同，SubText 不仅仅是修改现有文本，而是通过干预 LLM 的生成过程，将加密后的数据流“编织”进生成的文本中。

生成的文本（Stego Text）在语义上流畅自然，通过统计学检测的难度极高。系统内部集成了 LLMc (LLM Compression) 模块作为底层压缩引擎，配合安全层（Security Layer）和自适应动态分组（ADG）算法，实现了高容量、高隐蔽性的数据传输。

✨ 核心特性 (Features)

• 生成式隐写: 利用 LLM (如 Qwen 系列) 生成高质量的掩护文本，隐写痕迹难以察觉。
• 双模式编码:
  • 基础模式 (Standard): 传统的隐写模式，接收方需要知道 Prompt 才能解码。
  • Prompt 隐写模式 (Prompt-Hiding): 创新的链式隐写技术，将“掩护 Prompt”本身也嵌入到生成的文本中，接收方无需预先知晓 Prompt 即可实现盲解。
• 流式传输 (Streaming): 基于 Server-Sent Events (SSE) 的 API 设计，支持实时返回生成的文本片段，适合高并发场景。
• 多层安全架构:
  • 压缩层: 内置 LLMc 极大降低 payload 大小。
  • 加密层: 支持密码学加固，确保内容安全。
  • 隐写层: 自适应熵阈值 (Auto ADG) 算法，平衡生成质量与嵌入容量。

🛠️ 安装指南 (Installation)

本项目依赖 Python 3.11 环境。推荐使用 uv 进行依赖管理。

1. 克隆仓库

git clone https://github.com/sylym/subtext.git
cd subtext/LLMc

2. 创建并激活虚拟环境 (推荐 Python 3.11)

uv venv -p 3.11

根据你的操作系统激活环境：

• Linux / macOS

  source .venv/bin/activate

• Windows (PowerShell)

  .venv\Scripts\activate

3. 安装依赖

我们需要设置版本号环境变量以完成安装。

• Linux / macOS

  export SETUPTOOLS_SCM_PRETEND_VERSION="0.1.dev1"
  uv sync

• Windows (PowerShell)

  $env:SETUPTOOLS_SCM_PRETEND_VERSION="0.1.dev1"
  uv sync

🚀 服务部署 (Service Deployment)

SubText 通过 workflows 目录下的组件提供对外服务。通过 server.py 提供高性能的 HTTP 服务。

启动服务

您可以直接运行 workflows/server.py 来启动 FastAPI 服务。请确保通过环境变量指定模型路径。

# 设置模型路径环境变量并启动服务端 (默认端口 8001)
MODEL_PATH="/path/to/your/model" python -m workflows.server

# 例: 使用 Qwen3-4B-Instruct-2507 模型
MODEL_PATH="/path/to/Qwen3-4B-Instruct-2507" python -m workflows.server

⚙️ 服务配置参数 (Configuration)

服务端的关键运行参数定义在 workflows/server.py 文件的头部。您可以直接修改这些常量以适应您的硬件环境或业务需求。

1. 基础资源配置

参数	默认值	说明
MODEL_PATH	(Env Var)	模型路径。默认从环境变量 MODEL_PATH 读取，若未设置则使用硬编码的默认路径。
GPU_UTILIZATION	0.8	GPU 显存占用率。预分配显存比例 (0.0 - 1.0)。调高此值可增加 KV Cache 容量，但也增加 OOM 风险。
MAX_MODEL_LEN	35736	最大上下文长度。模型支持的最大 Token 序列长度，同时限制 stego_text 的最大输入长度。请根据显存大小适当调整。
PORT	8001	服务监听端口。API 服务启动的 TCP 端口号。

2. 并发与超时设置

参数	默认值	说明
MAX_CONCURRENT_TASKS	6	最大并发任务数。服务端同时处理的各种 Encode/Decode 请求的最大数量。
TASK_TIMEOUT_SECONDS	120	任务超时时间 (秒)。单次请求的最长执行时间，防止长任务阻塞资源。

3. 输入限制与安全配置

参数	默认值	说明
MAX_SECRET_LENGTH	2000	最大隐写内容长度 (字符)。限制 secret_text 的最大输入长度。
MAX_PROMPT_LENGTH	1000	最大 Prompt 长度 (字符)。限制 cover_prompt 的最大输入长度。
MAX_PASSWORD_LENGTH	100	最大密码长度 (字符)。限制 password 的最大输入长度。
DEFAULT_PASSWORD	"..."	默认密码。当请求中未提供 password 字段时使用的兜底加密/解密密码。

🔌 API 接口 (API Usage)

SubText 服务端提供基于 Server-Sent Events (SSE) 的流式 API，以支持实时的长文本生成与处理进度的反馈。所有接口均异步运行，适合高并发场景。

1. 隐写编码 (Encode)

将秘密信息嵌入到由 Prompt 生成的掩护文本中。

• Endpoint: POST /v1/stego/encode
• Content-Type: application/json
• Request Body:

参数	类型	必填	默认值	说明
secret_text	string	是	-	需要隐藏的秘密文本。
cover_prompt	string	是	-	用于生成掩护文本的提示词。
password	string	否	""	加密密码。若为空则使用默认密码加密。
encode_mode	int	否	0	0: 基础模式 (接收方需 Prompt) 1: Prompt 隐写模式 (接收方无需 Prompt)
auto_adg_thresholds	bool	否	true	true: 用更少的字隐藏更多信息 (生成较短，可能有生硬感) false: 文本自然流畅，抗检测能力强 (生成较长)
auto_complete	bool	否	true	是否自动补全结尾句子以保持语义完整。

• Response: text/event-stream (见下文流式响应协议)

---

2. 隐写解码 (Decode)

从隐写文本中还原秘密信息。

• Endpoint: POST /v1/stego/decode
• Content-Type: application/json
• Request Body:

参数	类型	必填	默认值	说明
stego_text	string	是	-	包含隐秘信息的完整文本。
password	string	否	""	解密密码。
cover_prompt	string	否	""	仅在基础模式下必填。若编码时 encode_mode=1，此处留空即可自动还原。

• Response: text/event-stream (见下文流式响应协议)

---

3. 流式响应协议 (Stream Response Protocol)

Encode 和 Decode 接口均返回 SSE 数据流。流中的每一行 data 均包含一个精简的 JSON 对象，客户端需根据状态码 s 解析内容。

JSON 字段定义:

字段	类型	说明	出现条件
s (status)	int	状态码： 🟢 0: 进度通知 (Progress) 🔵 1: 内容输出 (Stream Content) 🏁 2: 任务完成 (Finished) 🔴 3: 发生错误 (Error)	总是存在
p (percent)	float	当前任务进度百分比 (0.0 - 100.0)。	当 s=0 或 s=1 时
c (content)	string	生成的文本片段 (Fragment)。接收端应将其拼接到已有文本后。	仅当 s=1 时
r (result)	string	最终的完整结果文本 (Full Text)。	仅当 s=2 时
d (detail)	string	错误详情描述。	仅当 s=3 时

响应示例:

// 1. 进度通知 (s=0)
data: {"s":0,"p":5.0}

// 2. 流式内容输出 (s=1) - 包含片段 'c' 和进度 'p'
data: {"s":1,"c":"詹","p":12.0}
data: {"s":1,"c":"姆","p":12.5}
data: {"s":1,"c":"斯","p":13.0}

// 3. 任务完成 (s=2) - 返回完整结果 'r'
data: {"s":2,"r":"詹姆斯·邦德是小说家..."}

// (或者) 4. 发生错误 (s=3)
data: {"s":3,"d":"Processing failed."}

---

4. 服务健康检查 (Health Check)

检查服务运行状态及当前负载。

• Endpoint: GET /health
• Response: application/json

{
  "s": "r",  // 状态: "r" (running) 或 "f" (failed/starting)
  "a": 2,    // 当前活跃任务数 (Active tasks)
  "c": 6,    // 最大允许并发数 (Concurrency limit)
  "l": 2000, // 最大 secret_text 长度限制
  "p": 1000, // 最大 cover_prompt 长度限制
  "w": 100,  // 最大 password 长度限制
  "m": 35736 // 模型上下文窗口大小/最大 stego_text 长度限制
}

💻 Web 前端 (Web Frontend)

SubText 提供了一个轻量级的 Web 图形界面，位于 frontend/index.html。该界面完全基于浏览器端技术构建（HTML5 + Vue.js + Tailwind CSS），无需复杂的构建流程（如 Webpack/Vite），开箱即用。

主要功能

• 可视化交互: 提供直观的表单用于输入 Secret Message、Cover Prompt 和 Password。
• 响应式布局: 界面经过优化，完美适配移动端与桌面端。
• 实时流式显示: 利用 SSE (Server-Sent Events) 技术，实时展示隐写文本的生成过程，通过打字机效果呈现 LLM 的生成动态。
• 双模式支持: 完整支持 Standard (基础隐写) 和 Prompt-Hiding (Prompt 隐写) 两种模式的切换。
• 参数微调: 允许用户在界面上直接调整 ADG 阈值策略、自动补全等高级选项。
• 一键解码: 提供独立的解码面板，支持从生成的文本中快速还原隐秘信息。

如何使用

由于前端是一个纯静态 HTML 文件，您可以选择以下任意一种方式运行：

方式 1: 直接打开 直接双击 frontend/index.html 在浏览器中打开。

方式 2: 使用 Python 快速启动 在项目根目录下运行：

# 启动一个临时的静态文件服务器 (默认端口 8000)
python -m http.server 8000 --directory frontend

然后访问: http://localhost:8000

配置连接

注意：前端页面默认的 API 地址为相对路径 'api'。 如果您的服务端运行在本地 8001 端口或其他地址，请按以下步骤手动修改配置：

1. 使用文本编辑器打开 frontend/index.html。
2. 搜索代码中的 const apiBase。
3. 将其修改为您的实际服务端地址：

   // 修改前
   const apiBase = ref('api');
   
   // 修改后 (本地运行示例)
   const apiBase = ref('http://127.0.0.1:8001');

4. 保存文件并刷新浏览器即可生效。

⚠️ 免责声明 (Disclaimer)

在使用 SubText 项目（以下简称“本项目”）及其相关代码、模型或服务之前，请务必仔细阅读以下条款。使用本项目即表示您同意以下所有内容：

1. 仅供研究与教育用途: 本项目旨在探索大语言模型在信息隐藏、数据压缩与安全领域的学术潜力。所有的代码、算法及演示仅供技术研究、学术交流及教育目的使用。
2. 合规使用: 用户在使用本项目时，必须严格遵守所在国家或地区的相关法律法规（包括但不限于网络安全法、数据安全法、个人信息保护法等）。严禁将本项目用于任何非法用途，包括但不限于：
   • 传播非法、有害、暴力、色情或恐怖主义信息。
   • 进行网络攻击、逃避审查或传播恶意软件。
   • 侵犯他人隐私、知识产权或其他合法权益。
3. 生成内容责任: 本项目依赖于第三方大语言模型（如 Qwen, Llama 等）生成文本。生成的内容由模型决定，具有随机性和不可控性。开发者不对生成内容的准确性、完整性、客观性或合法性承担任何责任。
4. 无担保: 本项目按“原样”提供，不提供任何明示或暗示的保证（包括但不限于适销性、特定用途适用性或不侵权的保证）。
5. 责任限制: 在任何情况下，本项目贡献者、开发者或版权所有者均不对因使用或无法使用本项目而导致的任何直接、间接、偶然、特殊或后果性的损害（包括但不限于数据丢失、业务中断或利润损失）承担责任，即使已被告知此类损害的可能性。
6. 安全风险: 隐写术技术本身具有双刃剑属性。虽然我们致力于提升技术的安全性，但无法保证该技术不被滥用或破解。用户应自行评估使用该技术的风险。

📄 开源协议 (License)

本项目遵循 Mulan PubL v2 (木兰公共许可证, 第2版) 开源协议。

您可以在遵守协议的前提下免费使用、修改和分发本软件。详情请参阅 LICENSE 文件。