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

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

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

Model2App 项目海报：从模型 API，经 research、design、build 到 AI 应用

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

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

路径选择

第一次接触，建议先从体验指南开始；想完整学习开发流程，再看开发指南。已有基础可以直接进入快速开始，不必重复完成所有路径。

你的目标	推荐入口
先体验现成应用，再做小改造	我的第一个 AI 应用：用 WorkBuddy 改造配图助手
从首次调用开始，完整学习应用开发	模型 API 入门与 AI 应用开发指南
基于模型 API 开发可交互 AI App	快速开始 → 三步完成 → 拓展功能

查看现成案例：雾塔声纹室、文档整理工作台、旅行文章配图台。
进阶体验自动化流程：Agent Harness。
准备授课：课程资源导航。
操作遇到问题：常见错误与处理。

examples 提供三个桌面浏览器示例，使用相同的工作流、提示词基础部分和网页底座，模型资料与 02 个性化要求各不相同。完成正常主流程不需要进入示例目录运行命令，也不需要在示例目录重新配置密钥。

快速开始

Windows 使用 VS Code 的 Command Prompt 终端。下方以 # 开头的行是阅读说明，不要复制到 Command Prompt 中执行；只执行命令行。macOS 和 Linux 使用默认终端，克隆后可同样在 VS code中打开，为方便后续操作，建议后续操作均在VS Code的终端中展开。

1. 获取项目代码

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

# 进入项目目录
cd Model2App

2. 配置模型 API

本项目通过 API 使用沐曦 Token 资源包中的模型。资源包提供模型调用额度，访问令牌（API Key）是程序调用模型服务时使用的凭证。

符合条件的新用户可通过沐曦开发者社区 MACA 新人欢迎礼申领算力券，在模力方舟兑换后，用于抵扣沐曦 Token 资源包费用，具体以活动页和券面规则为准。购买资源包后，在“工作台 → 账号 → 访问令牌”创建通用令牌，并授权已购买的沐曦资源包；已有可用资源包和令牌的用户可直接配置。

首次使用可先打开沐曦 Token 资源包上手指南，按步骤完成算力券兑换、资源包购买和访问令牌创建，再回到这里填写项目配置。

复制配置模板：

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

macOS 和 Linux 使用 cp .env.example .env.local。在 .env.local 中将令牌占位文字替换为真实令牌。下面以模型研究与代码生成都使用 Atria-Dawn-Preview 为例：

# 共用访问配置（生成应用也复用）
GITEE_AI_TOKEN=请替换为你的访问令牌
GITEE_AI_BASE_URL=https://api.moark.com
GITEE_AI_PACKAGE_ID=1492

# 首次调用、模型研究与需求整理
# 可替换为 GLM-5.3 或 Qwen3-Coder-30B-A3B-Instruct（先确认资源包可用）
TEXT_MODEL_NAME=Atria-Dawn-Preview

# 页面、代码生成及修复（复用上面的访问配置）
CODE_MODEL_NAME=Atria-Dawn-Preview

TEXT_MODEL_NAME 用于首次调用、模型研究和需求整理，CODE_MODEL_NAME 用于页面、代码生成及修复；两者共用 GITEE_AI_* 访问配置。

想尝试其他开发模型，可在 .env.local 中分别修改这两个模型名，例如选用沐曦 Token 资源包中可用的 GLM-5.3 或 Qwen3-Coder-30B-A3B-Instruct，无需修改 Python 代码。

沿用旧 .env.local 时，核对 GITEE_AI_BASE_URL 与当前模型资料的 API 地址一致；本版三个示例使用 https://api.moark.com。

生成应用复用 GITEE_AI_* 访问配置；应用使用的语音、图像或文档模型由 workspace/input/模型API资料.md 指定。开发模型也可以更换为其他兼容 Chat Completions 的模型，修改相应配置即可。

编程助手（可选）：可参考模力方舟官方文档接入资源包中的模型。助手与本项目分别配置；本项目仍需填写上述配置，真实令牌只保存在本地，不发到对话中。

本项目的命令共用根目录这份密钥配置。 后续 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 时，只需再次激活。更新项目后，在同一环境运行 python -m pip install -r requirements.txt 更新依赖；其中 pypdf 用于 PDF 页数读取，无需重新生成网页。

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

# 重新激活已经创建的虚拟环境
.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：生成设计需求与页面预览

设计提示词分为上方的通用基础要求和下方的“补充要求”。基础页面默认采用桌面左右分栏，保留完整输入、参数设置、调用与结果下载；下方保留雾塔声纹室的 TTS 示例。使用其他模型时，将“补充要求”整段替换为自己的场景，或填写“无”生成基础页面，不需要另建资料文件。

个性化部分可以写名称、桌面布局、参数预设，以及图片和音频的公开 URL 与来源；明确指定的布局和分栏比例优先于基础默认值。预设仍使用当前模型的参数，不增加其他模型或自动发布功能。

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

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

参数以平台模型介绍、接口文档和体验代码的合集为依据，不因旧笔记标为“未实测”而删去平台已说明的参数。常用项放首屏，其余放“高级设置”，预设不能代替完整参数，未选模式的专属参数不发送。只改主题或布局时，修改“补充要求”后重跑 design，可复用原研究笔记；只改生成的需求摘要不会更新页面。

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

遇到 429 时查看返回原因：限流时等待，余额或额度不足时先处理额度；需求已保存且相关输入未修改时，用 design --retry 继续。页面生成成功后再运行 build。

Step 3：生成 Web 项目

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

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

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

运行生成项目

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

在桌面浏览器打开终端显示的网址，先用短文本或 8 MB 以内的小文件试一次，检查结果能否预览和下载。应用沿用根目录 .env.local，不用再次配置密钥。预设按钮只填参数，点击生成才会调用模型；异步任务需要等待，请勿连续提交。终端中的 INFO 和 200 OK 通常是正常请求日志，报错时再查看对应操作。

页面的调用示例随参数更新，“复制示例代码”复制简短示例，“下载完整代码”下载包含运行内核的完整脚本；示例需在生成项目目录运行。调用失败时先检查配置、网络、输入或参数；代码问题见下方“项目修复”。结果、调用脚本和原始响应保存在 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 配置；成品修改后的启动、检查和保留方法见模型 API 入门与 AI 应用开发指南。

常见错误与处理

查看终端最后一条错误，按下表处理。分享报错时隐藏访问令牌；配置、网络和端口问题不需要运行 repair。

错误或现象	处理方法
找不到 Python、`model2app.py`，或提示 `ModuleNotFoundError`	按运行环境配置确认 Python 已安装；在项目根目录激活 `.venv`，缺少依赖时运行 `python -m pip install -r requirements.txt`。
提示缺少访问令牌	确认项目根目录有 `.env.local`，并已填写 `GITEE_AI_TOKEN`；首次使用可复制 `.env.example`，不要覆盖已有配置。
`401 Unauthorized` / `403 Forbidden`	核对令牌、API 地址及资源包授权是否匹配；使用本项目默认配置时，确认令牌已授权资源包 `1492`。文件已改但仍失败时，检查下方的环境变量覆盖问题。
`429`	查看返回的具体原因：限流时等待后再试；余额或额度不足时先检查账号与资源包额度，反复重试不会解决。
`400` / `422` 参数错误	根据具体报错核对必填项、参数名、类型、范围和模式组合，以当前平台资料为准，不要仅凭状态码删除参数。
超时、断连，或一直只有思考、没有正文	等待终端给出完成或失败结果；超时、断连后检查网络与服务状态，再恢复失败步骤。同一开发模型反复无法完成时，可更换有权限使用的 `TEXT_MODEL_NAME` 或 `CODE_MODEL_NAME`。
需求已保存，但页面生成失败	等本次自动纠正结束；相关输入未修改时运行 `python model2app.py design --retry`。修改过笔记、需求或提示词时重跑 `design`；原始资料变化时先重跑 `research`。
页面已通过，但 `build` 失败	等本次自动纠正结束；仍失败时查看终端错误和 `workspace/artifacts/03-项目生成原始回复.txt`，处理原因后重跑 `python model2app.py build`。模型调用或本地检查失败时，不会替换旧成品。
启动时提示端口被占用	使用已启动的服务，或在旧服务终端按 `Ctrl+C` 停止；也可将根目录 `.env.local` 的 `PORT` 改为 `3001`，重启 `serve` 并打开新地址。

更多情况见开发指南的常见问题速查。使用 Harness 时，按其失败恢复说明续跑。

拓展功能

项目修复

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

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

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

进一步体验 Agent Harness

Agent Harness 是围绕模型组织任务执行的程序。本项目在原有 research → design → build 三步工具的基础上，增加了步骤之间的自动衔接，以及根据执行结果继续、修复或停止的判断。原来由你查看结果、决定运行下一个命令；现在由代码依据预设规则完成这部分判断，模型负责制定计划和生成内容。

harness/ 文件夹已备好「雾塔声纹室」TTS 示例。完成前面的环境准备后，在仓库根目录运行：

python harness/run.py

生成完成后，运行 python harness/run.py serve 使用应用。更换模型、调整提示词、查看过程和恢复失败步骤，见详细使用说明。

下一步：尝试自研 Agent

了解调度与检查代码后，尝试让模型根据目标和工具结果选择下一步，见自研 Agent 指引。

课程资源

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

资源	适合谁	内容
我的第一个 AI 应用：用 WorkBuddy 改造配图助手	想先体验的使用者	运行现成文生图工具，理解 API 调用，再改配色和名称
模型 API 入门与 AI 应用开发指南	学习者	课前准备、三项核心任务与可选拓展
课程大纲	授课教师	教学目标、课堂流程、风险处理与评价方式
课堂任务	学习者、教师	核心任务与项目发布的快速索引
课程资源导航	所有人	全部课程材料与推荐阅读顺序

开源你的 AI 应用

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

根目录 workspace 默认不提交本地生成的预览和成品源码，examples 中保留参考成品。若要在自己的仓库发布新作品，请在发布副本中调整相应的 .gitignore 规则，并继续排除密钥、结果和备份；具体操作见模型 API 入门与 AI 应用开发指南。

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

想让别人直接打开使用？

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

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

安全说明

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

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

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