---
myst:
  html_meta:
    "moi:status": "verified-live-20260723"
---

# 教程:把一门课的资料变成能回答问题的知识库

本教程用一批真实资料——李宏毅《生成式AI导论》第一讲课件(PDF 与 PPTX 各一份)——在 MOI 中完整走一遍:登录、安置数据、加工、建成知识库,直到问答。每一步写明您做什么、平台随即发生什么、您应看到什么;实际运行中遇到的失败与排查过程原样保留,它们和成功路径同样重要。

本教程的全部内容来自 2026-07-23 在 MOI 上的一次实际操作记录。

## 第 1 章 · 进门

打开 MOI,登录页提供手机号与邮箱两种方式,默认验证码登录,可切换密码登录。

登录后,顶栏分三个区:**应用、智能体、数据**,并显示当前工作区名称。本教程全程在「数据」区,它的左侧栏即数据工作的全部入口:数据连接(连接器、通道管理、载入任务、导出任务)、数据处理(工作流、SQL 编辑器)、资源中心(Catalog、计算资源、数据分享、知识库)、监测(SQL 历史、作业、操作日志)、用户权限。

首屏仪表盘显示四项资产计数:Catalog 数据对象、工作流、计算资源、知识库。

## 第 2 章 · 安置:给这批文档一个位置

**您做**:进入 资源中心 → Catalog,点「新建目录」,创建目录 `genai_course`;进入该目录,「新建数据库」创建 `course_materials`;进入该库,点「创建」下拉选「卷」,创建文件卷 `lecture_docs`。

**平台随即**:三层对象在目录树中登记完毕。数据的归属层级为:工作区 → 目录 → 数据库 → 表 / 文件卷。系统目录不能存放用户数据卷,选择器中呈灰色。

**您应看到**:目录树出现 `genai_course / course_materials / lecture_docs`。

### 上传文件

文件卷页面本身没有上传按钮——上传的入口在 **数据连接 → 载入任务**。

**您做**:点「创建任务」。任务类型第一层就是数据形态的分岔:**非结构化**(文档、音视频、图片,载入到数据卷)或**结构化**(CSV/XLSX,导入表)。选非结构化;数据来源选「本地上传」;数据卷选 `lecture_docs`;把两份课件拖入上传区;点「创建并开始载入」。

限制与选项(本次实测值):单次最多 20 个文件、单个不超过 200MB;去重策略按文件名与 MD5 判断,可选跳过或覆盖;可按文件类型与路径正则筛选;来自连接器的持续载入支持周期执行。

**平台随即**:生成一条载入任务(本次 ID 700941000002),逐文件执行。

**您应看到**:任务详情页显示「已完成,共 2 个文件,成功 2 个,失败 0 个」,并逐文件列出状态与起止时间;回到 Catalog,`lecture_docs` 卷内出现两份文件,可下载、预览、删除。

## 第 3 章 · 做熟:一条加工工作流

**您做**:进入 数据处理 → 工作流,点「创建工作流」。创建方式有三种:系统模板(九个,覆盖文档知识库准备、信息提取、图纸解析、语音/视频转录问答等)、空白创建、导入 DSL 创建。选模板「**文档知识库准备**」——它的说明就是本教程的任务:将 PDF、Word、PPT 等资料解析、清洗、切分、向量化并写入知识库,为后续 RAG 问答提供可检索的数据基础。

模板展开为六步运行配置:

| 步骤 | 本次配置 | 说明 |
|---|---|---|
| Catalog 数据源 | `lecture_docs` 卷 | 计算资源默认「跟随工作流默认」,发布后为共享 Worker |
| 文档解析 | 默认 qwen3-vl-plus | VLM OCR 模型,处理图片、扫描件与复杂版式 |
| 按长度切分文档 | 默认 512 / 50 | 文本块最大字符数 / 相邻块重叠字符数 |
| 构建知识库索引 | 新建知识库,嵌入模型 bge-m3 | 三级索引(doc/section/chunk)默认开启,Section 大小 5 |
| 写出文档文件 | 无需配置 | 解析产物写为文件 |
| 保存到 Catalog | `parsed_docs` 卷(选择器内联新建) | 解析结果文件的存放位置 |

另可配置完成通知 URL:工作流执行完成或失败时,平台向该地址 POST 通知。

**平台随即**:配置确认后进入画布——七个节点已连成一条链:读取源文件 → 解析 → 切分 → 构建索引 → 写出文件 → 保存目录 → 登记血缘。顶栏「预览 DSL」可随时查看这张图对应的工作流定义文件;画布、定义文件与模板产出的是同一份定义。点「完成」保存发布后,平台自动发起了第一次运行。

**您应看到**:工作流列表中状态为「可运行」,计算资源「共享 Worker」;监测 → 作业中出现运行记录——**每个文件一条作业**。

### 本次实际运行:两次失败,各有一个明确病根

真实运行很少一次全绿。本教程第一次运行两个文件全部失败,排查与修复过程如下——排查入口都是同一个:作业列表 → 失败记录的详情页,那里有完整的错误信息、失败节点、Trace 标识链与「重跑」按钮,以及整条链路的节点状态拓扑图。

**失败一:嵌入模型 404。** PDF 作业运行 19 秒后失败,拓扑图显示解析与切分已完成(切出 143 个文本块),失败在构建索引节点:

```text
CreateEmbeddings(model=BAAI/bge-m3 ...): Embedding failed: OpenAI error:
status 404, {"code":"model_not_available"}
```

病根:建库时嵌入模型下拉中存在两个同名候选——「bge-m3 / BAAI/bge-m3」与「TaaS Embedding / bge-m3」,前者的注册名在模型服务端不存在。改用「TaaS Embedding / bge-m3」重建知识库后,该节点通过。

**失败二:PPTX 缺少转换后端。** PPTX 作业启动约 1 秒即失败,错误信息:

```text
parse v3 (type=pptx): convert pptx to pdf failed (primary + soffice):
soffice executable file not found in $PATH; parser_backends=[]
```

PPTX 的解析路径是先转换为 PDF 再解析;本环境的执行进程未接入任何解析后端,系统回退到本机 soffice,而它未安装。此问题属于部署环境配置,与工作流定义无关。本次实测保留 PDF 单轨继续。

修复嵌入模型后重新运行:**PDF 作业 37 秒完成,全节点绿色**——解析、切分、向量化、写入索引、登记血缘一次走通。

## 第 4 章 · 立库:知识库已经有了内容

知识库在第 3 章配置索引步骤时已经创建;工作流执行成功后,它不再是空壳。

**您应看到**:资源中心 → 知识库,知识库卡片显示「1 文件」。

知识库详情有三个部分:**数据源**(按结构化程度展示已关联的文件和表——知识库同时容纳两类数据)、**语义配置**(维度列、事实列、业务指标、表关联、标准问答、术语解释、规则注入等条目,供自然语言查询理解表数据时使用,可导入导出与校验)、**智能体关联**。

卡片的编辑入口中有一栏**备注说明内容**(必填):填写这个知识库的用途与可回答的问题列表,供智能体在多个知识库之间精准选择。本次填写包含一条边界约定:「课件未涉及的内容,应如实说明材料中未找到,不要猜测。」

## 第 5 章 · 对答:当前的真实边界

**您做**:知识库 → 对话,新建对话;输入框上方挂载知识库「李宏毅生成式AI课程」;模型选择 glm-5.1;提问:「这门课的预修要求是什么?需要先修过人工智能或数学、会写程序吗?」——这是一道课件中有明确答案的题(课件「课程定位」页写明:预修课程无,三句「不预设」)。

**实测结果(2026-07-23)**:回答未基于知识库。模型自述:「我当前的工具配置中没有知识库检索工具(如 RAG 搜索、SQL 查询等),因此无法从知识库中查找。」消息气泡上知识库标签在、开发者视图的调用记录显示输入 token 仅 1.95k——上下文中没有任何检索片段。即:**知识库选择与传递成功,但对话侧的检索工具未接通,问答尚不能基于知识库作答**。定位信息(trace_50b0a7ddc163ad8d54de4f338bd35c89)已可供排查。

知识库建成与问答联通之间的这最后一段,以产品修复为准;本教程将在联通后补全本章的验证方法——届时用两类问题验收:课件中确有答案的(检验答案与引用),课件中没有答案的(检验是否如实说明检索不到)。

## 本次教程覆盖的链路

| 环节 | 实测状态 |
|---|---|
| 登录、目录/数据库/文件卷创建 | 走通 |
| 本地上传(载入任务) | 走通,2/2 成功 |
| 模板创建工作流、发布、运行 | 走通 |
| PDF 解析 → 切分 → 向量化 → 索引 → 血缘 | 走通,37 秒 |
| PPTX 解析 | 失败:环境缺转换后端(见第 3 章) |
| 知识库成库 | 走通,1 文件 |
| 知识库问答 | 未通:对话侧缺检索工具(见第 5 章) |
| 智能体使用知识库 | 未覆盖,待问答联通后继续 |

> 面向 AI 代理的说明:本页每一步的界面名词、默认值与错误信息均来自实际运行;执行同类任务时,以「作业」详情页的错误信息与 Trace 标识为排查起点;嵌入模型选择「TaaS Embedding / bge-m3」;PPTX 解析依赖部署环境的转换后端。