Model2App

选一个模型，做出一款自己的 AI 应用。

Model2App 是一套面向 API 初学者的 AI 应用开发工具包，也是 API 入门课程的配套项目。基于沐曦 Token 资源包，通过 research → design → build，从读懂模型资料、设计使用场景，到生成能真实调用模型的应用。

从一间自己的「雾塔声纹室」开始：写下文字、选择音色、调整情感，为口播、文章伴读或演示旁白制作声音素材。也可以跟着示例，把文档解析做成「文档整理台」，把文生图做成「灵感画布」，再换上自己的主题和用途。

无需下载模型或配置本地 GPU。学生手册、资料模板、提示词和完整示例都已提供；你既能跟着做，也能看懂参数如何影响结果、页面如何调用 API。研究笔记、设计需求和生成代码都会保留，方便继续修改，或换一个模型沿用这套流程。

路径选择

你的目标	推荐入口
第一次学习 AI 模型 API	学生手册
基于模型 API 开发可交互 AI App	快速开始 → 三步完成 → 拓展功能
查看 AI 应用案例	声音工作台、文档整理台、灵感画布
组织 AI 模型 API 实践课程	课程资源导航

examples 提供可选参考案例。完成正常主流程不需要进入示例目录运行命令，也不需要在示例目录重新配置密钥。

快速开始

Windows 使用 VS Code 的 Command Prompt 终端。下方以 # 开头的行是阅读说明，不要复制到 Command Prompt 中执行；只执行命令行。macOS 和 Linux 使用默认终端。

1. 获取项目代码

# 克隆项目到本地
git clone https://gitlink.org.cn/ccf-ai-infra/Model2App.git

# 进入项目目录
cd Model2App

2. 配置模型 API

在模力方舟注册账号，领取教师提供的算力券并购买沐曦 Token 资源包，再到“个人工作台 → Token 资源包”创建访问令牌。复制配置模板：

# 复制配置模板，生成本地配置文件
copy .env.example .env.local

macOS 和 Linux 使用 cp .env.example .env.local。在 .env.local 中填写：

# 沐曦 Token 资源包访问令牌，用于模型研究和真实 API 调用
GITEE_AI_TOKEN=沐曦Token资源包访问令牌

# 编程模型，用于生成页面和调用代码；填写你实际开通的服务
CODE_MODEL_API_KEY=编程模型访问令牌
CODE_MODEL_BASE_URL=https://ai.gitee.com/v1
CODE_MODEL_NAME=qwen3.8-flash
CODE_MODEL_PACKAGE_ID=

两组配置分工不同：GITEE_AI_TOKEN 用于沐曦资源包中的模型研究与目标模型调用；CODE_MODEL_* 用于生成页面和调用代码。

编程模型也可以选自沐曦 Token 资源包：先在资源包页面确认适合编程模型及其准确名称，再填写 CODE_MODEL_*。两组配置使用同一资源包、令牌有相应权限时，可以使用同一个令牌，编程模型资源包编号填 1492。工具包也兼容模力方舟其他资源包和其他 Chat Completions 服务；使用时将令牌、地址、模型名和资源包编号配成同一组，没有资源包编号则留空。

模板保留了默认编程模型名，使用其他模型时请修改 CODE_MODEL_NAME，不是只换密钥。调用编程模型的公共代码集中在 scripts/common.py 的 request_chat() 中，通常改配置就够了；生成应用调用目标模型的代码则在 workspace/web-project/model_adapter.py。

如果还想让编程助手使用沐曦 Token 资源包中的编程模型，可参考 模力方舟官方文档 中对应助手的接入说明，选择资源包内已开通、且助手支持的模型。助手的配置与本项目配置是分开的，按下文命令操作仍需填写 CODE_MODEL_*。不熟悉配置项时，可以请助手解释 .env.example，真实令牌由你填入本地配置，不要发到对话中。

本项目的命令共用根目录这份密钥配置。 后续 call、research、design、build、serve、repair 和 agent 命令都会自动读取 .env.local，不要把真实密钥复制到模型资料、生成项目或示例目录。

3. 安装并配置 Python 运行环境

目标模型通过沐曦 Token 资源包的远程 API 调用，本地 Python 用于运行工具包和生成的应用，不需要下载模型权重或配置 GPU。

安装 Python 3.12 或兼容版本。Windows 安装时勾选 Add python.exe to PATH，安装后重启 VS Code。在项目根目录创建并激活虚拟环境，再安装依赖：

# 检查 Python 是否安装成功及当前版本
python --version

# 创建名为 .venv 的虚拟环境
python -m venv .venv

# 激活虚拟环境
.venv\Scripts\activate

# 安装 requirements.txt 中的项目依赖
python -m pip install -r requirements.txt

终端开头出现 (.venv) ，说明虚拟环境已经激活。以后重新打开终端或 VS Code 时，只需在项目根目录再次运行激活命令，不用重新创建环境或安装依赖。

重新激活虚拟环境的命令：

# 重新激活已经创建的虚拟环境
.venv\Scripts\activate

macOS 和 Linux 将前两条命令中的 python 换成 python3，使用 source .venv/bin/activate 激活环境；激活后其余 python 命令相同。

环境准备遇到困难时，也可以请已有的 Codex、Cursor 或 WorkBuddy 等助手协助检查 Python、创建虚拟环境和安装依赖。说明“按本节要求准备环境，不改项目代码”，需要安装权限时由你确认；准备好后，继续按下文步骤操作。助手只是可选帮助，不需要为了完成课程另装一套工具。

三步完成：从模型 API 到 AI 应用

模型 API 原始资料
      ↓ python model2app.py research
模型学习笔记
      ↓ python model2app.py design
AI 应用设计需求 + 可打开的静态页面
      ↓ python model2app.py build
场景化 AI Web 应用

按顺序完成模型研究、应用设计和项目生成，每一步的结果都会保存在 workspace 中，方便查看与修改。可以先选择 IndexTTS-2，按下面的步骤收集资料，配合示例提示词制作“雾塔声纹室”；也可以选择其他模型，做自己的 AI 应用。

Step 1：研究模型

先填写 模型 API 资料：按模板指引，从模力方舟复制模型介绍、体验代码和对应接口文档。可以对照 TTS 示例 填写；找不到的内容如实注明，代码中的真实令牌换成 YOUR_TOKEN。

# 整理模型资料，生成学习笔记
python model2app.py research

脚本会将模型资料和 研究提示词 提交给文本模型，生成 模型学习笔记。

先核对 API 地址、调用流程和完整参数清单：每个参数做什么、怎么填，有哪些范围或配合关系。以原始资料为准，未确认的内容标为“待验证”；修正笔记后再进入下一步。想调整学习重点，可以修改研究提示词后重跑。

Step 2：生成设计需求与页面预览

把模型能力放进具体场景。第一次可以跟着示例做一间 雾塔声纹室：一间原创魔法学院里的声音小屋，输入台词、选择音色和情感，制作可以试听和下载的声音。设计提示词已准备好，可以直接使用。

也可以把准备好的稿件做成小红书口播、公众号伴读、知乎讲解或 Web PPT 旁白；换用文档解析、文生图模型，则可以做资料整理台或文章配图工具。先完成输入、生成和导出，不必加入自动发布等功能。

# 生成设计需求和静态页面
python model2app.py design

脚本会读取原始资料、学习笔记和 设计提示词，生成 应用设计需求 和静态页面。打开 workspace/design-preview/index.html 查看预览；此时还不会调用目标模型。先对照模型资料核对需求摘要和页面，重点确认输入方式、可调参数和结果形式，避免出现模型不支持的功能。

已确认的可调参数都应有入口：常用项放首屏，其余放“自定义参数”，预设按钮不能代替完整参数。想改主题或布局，修改设计提示词中的“补充要求”后重跑 design；只改生成的需求摘要不会更新页面。

页面结构或参数约定检查未通过时，脚本最多自动请求编程模型纠正一次，请先等待结果。若最终失败、需求已保存，按终端提示运行 python model2app.py design --retry 恢复页面阶段，不用重跑研究。恢复前修改过笔记、需求或提示词时，运行完整的 design；原始模型资料有变化时，先重跑 research。

Step 3：生成 Web 项目

# 为预览页面接入模型 API，生成完整项目
python model2app.py build

脚本会根据模型资料、页面设计和 生成提示词，生成模型调用代码，与预览页面组装成 完整项目，保存在 workspace/web-project。配置读取、结果保存和脚本导出由工具包自带的 通用底座 提供，无需另行配置。

生成的调用代码未通过本地检查时，同样最多自动纠正一次。检查通过后，按下文启动应用，验证一次真实调用。模型生成记录 可用于查看和排查生成的代码。

运行生成项目

# 启动已生成的应用
python model2app.py serve

打开终端显示的网址，先用短文本或 8 MB 以内的小文件试一次，检查结果能否预览和下载。应用沿用根目录 .env.local，不用再次配置密钥。预设按钮只填参数，点击生成才会调用模型；异步任务需要等待，请勿连续提交。

调用失败时先按页面提示检查配置、网络、输入或参数，不必从头重做；代码问题见下方“项目修复”。结果、调用脚本和原始响应保存在 workspace/web-project/outputs。按 Ctrl+C 停止服务，重新生成前也要先停止。

后续修改可以按这张表操作：

想调整什么	改哪里	重新运行
名称、主题、布局或使用场景	设计提示词的“补充要求”	design → build → serve
参数控件、分组或预设	核对学习笔记的参数表，在设计提示词中说明调整	design → build → serve；资料变了先重跑 research
更换目标模型	更换模型 API 资料，删除或替换设计提示词中的 TTS 示例段	research → design → build → serve

换模型后只保留通用设计要求、“补充要求”保持“无”，也可以生成基础应用。想直接改成品，可编辑 static/ 页面和 model_adapter.py 调用代码；先备份，并把需要保留的要求写回提示词，避免下次生成时丢失。

借助编程助手继续开发（可选）

沐曦 Token 资源包为应用提供语音合成、文档解析、图像生成等模型能力。应用跑通后，可以继续借助 Codex、Claude Code、Cursor、TRAE、OpenCode 等编程助手，或 WorkBuddy 这类 AI 工作助手，调整界面与功能。选自己熟悉的工具即可，不必全部安装。

把模型资料、学习笔记、设计提示词和当前代码作为参考，让助手在已有应用上继续修改。助手帮助你写代码，应用中的实际生成和解析仍通过沐曦 Token 资源包的模型 API 完成。读懂接口和参数后，你也能更明确地说明要保留哪些能力，以及怎样检查修改结果。

例如，先备份成品，再向助手提出：

请参考模型资料和当前项目，把“雾塔声纹室”改成博物馆语音导览工具。调整页面和示例文案，保留现有音色、情感参数、通过沐曦 Token 资源包调用模型的代码和下载功能，不增加新模型。先说明修改方案，确认后再修改和检查；不要读取或输出密钥。

助手的模型接入方式见前面的 API 配置；成品修改后的启动、检查和保留方法见 学生手册。

拓展功能

项目修复

遇到代码或交互问题，先停止服务，把操作步骤和报错写入 项目问题记录，再运行：

# 根据问题记录修复生成项目
python model2app.py repair

修复前的文件会备份到 workspace/repair-backups。完成后运行 python model2app.py serve，重复原操作确认问题已解决。密钥、网络或端口问题应先检查环境，不需要让模型改代码。

进一步体验 Agent Harness

前面的三步由你运行命令、检查结果；Agent Harness 可以把这些步骤连接起来，自动执行。建议先手动学习，再体验 Harness，不必每次都把两种方式各做一遍。

Harness 是围绕模型运行的程序，负责准备资料、连接工具、记录结果和处理错误。本项目提供固定流程的简化实现：请模型制定计划，再执行 research → design → build 并检查项目；运行检查不通过时，最多修复两轮。生成失败或超时会停止。

沿用前面的模型资料、设计提示词和密钥，在 Harness 任务需求 中补充本次目标，也可直接用默认任务。先停止应用，并另存需要保留的成果，因为这次会重新生成：

# 使用 Agent Harness 生成并检查应用
python model2app.py agent

完成后查看 运行报告。临时检查服务会自动关闭，再运行以下命令使用应用：

# 启动已生成的应用
python model2app.py serve

自动检查验证本地代码和页面，不调用目标模型；仍需在网页中测试真实结果与下载。计划、研究和生成过程会使用模型 API。

手动三步和 Harness 都将成品保存在 workspace/web-project。下次使用时，重新激活虚拟环境，运行 serve 即可，不用再运行 agent。换模型或改 UI 仍按上表操作；具体说明见 学生手册。

下一步：尝试自研 Agent

体验时留意三个问题：模型负责什么、Harness 调用了哪些工具、程序如何判断完成。本例由 Python 安排执行顺序，模型负责计划和内容生成，并不自主选择工具。可以先修改任务，再阅读 scripts/agent.py 和 检查代码，尝试增加一条检查；理解后再探索让模型根据工具结果决定下一步。

课程资源

课程从 API 基础和首次本地请求开始，逐步进入三步 Web 制作流程，并提供项目修复、Agent Harness 和个人项目开源等拓展内容。

资源	适合谁	内容
学生手册	学习者	课前准备、三项核心任务与可选拓展
课程大纲	授课教师	教学目标、课堂流程、风险处理与评价方式
课堂任务	学习者、教师	核心任务与项目发布的快速索引
课程资源导航	所有人	全部课程材料与推荐阅读顺序

开源你的 AI 应用

只分享应用时，整理 workspace/web-project 的源码、依赖、配置模板、运行说明和素材声明，并带上根目录的 LICENSE；底座已经在成品内。分享完整开发过程时，还要保留 prompts、scripts、templates、入口文件及经过核对的模型资料与生成记录。

本仓库默认不提交本地生成的预览和成品源码。若要在自己的仓库发布它们，请在发布副本中调整相应的 .gitignore 规则，并继续排除密钥、结果和备份；具体操作见 学生手册。

发布前排除 .env.local、.venv、缓存、上传文件、运行结果和备份，检查资料与记录中没有访问令牌或个人信息。详细范围见共建指南。

想让别人直接打开使用？

发布源码和部署应用是两件事。上线时，把生成的 workspace/web-project 作为独立 Python 应用部署到支持常驻进程的服务器或托管平台，安装其中的 requirements.txt，在平台环境变量中配置目标模型令牌，再按平台指定端口启动 uvicorn app:app --host 0.0.0.0 --port 8000（端口以平台要求为准）。不能只上传 HTML 到静态网站托管，因为模型调用需要 Python 后端。

对外开放前配置 HTTPS、访问权限、请求限流和额度限制，并考虑长任务的代理超时以及结果文件的定期清理。访问者使用的是你后端配置的模型额度；编程模型只在制作应用时使用，成品运行通常不需要编程模型密钥。先做受控的小范围试用，具体步骤见 学生手册。

安全说明

• 访问令牌只写入项目根目录 .env.local，整个主流程只配置一次；
• 不把令牌写进浏览器代码、提示词或模型资料，发布前再检查保存脚本和日志；
• .gitignore 排除本地配置与运行结果，但普通压缩打包仍需检查文件清单；
• 项目修复和 Agent Harness 不提交 .env.local，并在提交源码前替换已知密钥。

生成应用默认只监听本机，未包含账号鉴权、访问限流等公开服务措施；若要给他人在线使用，需另做部署与安全处理。

项目改进和课程资源维护参见 CONTRIBUTING.md。本项目采用 MulanPSL-2.0 开源协议。