generative-ai-for-beginners 第 08 课实战用 Python 脚本把 YouTube 转录文本加工成语义搜索 Embedding 索引【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners本文围绕 generative-ai-for-beginners 课程第 08 课《构建搜索应用》配套的转录数据准备脚本位于 08-building-search-applications/scripts完整讲解从创建 Azure OpenAI Service 资源、配置环境变量、安装 Python 依赖到依次运行六个数据处理脚本最终生成可用于语义搜索的 Embedding Indexembedding_index_3m.json的端到端流程。读完本文你将掌握这套YouTube 转录文本 → 说话人识别 → 分桶切块 → 摘要生成 → 向量化嵌入流水线的每个环节并理解每个脚本的源码级实现细节。一、这套脚本解决什么问题在第 08 课的语义搜索示例中我们需要对 Microsoft AI Show 频道YouTube 播放列表 ID 为PLlrxD0HtieHi0mwteKBOfEeOYf0LJU4O1的每期节目视频建立全文检索能力。用户输入自然语言问题后搜索应用需要返回视频中哪一段最可能包含答案以及对应的视频链接和起始时间点。要做到这一点前提是先把每期视频的转录文本Transcript下载下来并加工成带时间戳、带说话人、带摘要、带语义向量的结构化索引。转录数据准备脚本就是完成这一前置工作的工具链。根据 08-building-search-applications/README.md 的说明索引由一系列 Python 脚本生成脚本位于scripts文件夹并配合启动脚本.sh/.ps1/.bat按固定顺序执行。原文档明确说明完成第 08 课本身不需要运行这些脚本因为课程已直接提供现成的embedding_index_3m.json但对于希望用新数据如自己频道的视频、新一期节目重建索引的读者这套脚本就是标准答案。需要说明的是本文所引用的脚本即为本仓库内 08-building-search-applications/scripts 目录下的实现无需再从外部克隆示例仓库直接在本仓库对应目录下运行即可。脚本已在 Windows 11、macOS Ventura 与 Ubuntu 22.04及更新版本上测试通过。二、整体数据流水线概览从启动脚本 prepare_transcripts_ai_show.sh 和 prepare_transcripts_ai_show.ps1 的注释可以看到整条流水线共分六个阶段下载转录文本调用transcript_download.py从指定 YouTube 播放列表批量下载每期视频的转录保存为videoId.json元数据 videoId.json.vtt转录内容说话人识别调用transcript_enrich_speaker.py用 OpenAI 函数调用Function Calling从前 3 分钟转录中抽取说话人姓名并写回元数据分桶切块调用transcript_enrich_bucket.py把长转录按分钟数默认 3 分钟可配置切成带重叠上下文的小段摘要生成调用transcript_enrich_summaries.py用对话模型把每个分段的文本压缩成约 60 词的摘要向量化嵌入调用transcript_enrich_embeddings.py用text-embedding-ada-002把每个分段文本转为 1536 维向量精简输出调用transcript_enrich_lite.py生成去掉正文text字段的轻量版索引只保留摘要、向量等用于压缩存储。课程文档对最终效果的描述是每个 3 分钟文本段约包含来自下一段的 20 个词的重叠目的是保证段落语义不被截断并提供更好的搜索上下文每段经过 60 词摘要与 1536 维向量化后写入embedding_index_3m.json搜索应用将其加载进 Pandas DataFrame再用余弦相似度nearest neighbor search对查询向量做最近邻匹配。三、创建 Azure OpenAI Service 资源脚本依赖 Azure OpenAI Service 提供的 Embedding 与对话Responses API能力。按照原文档使用 Azure CLI 依次完成以下操作。文档建议先将 Azure CLI 更新到最新版本以确保与 OpenAI 的兼容性。1. 创建资源组原文档使用名为semantic-video-search的资源组位于 East US。可自定义名称若更换位置需对照模型的区域可用性表确认目标模型在该区域可用。az group create --name semantic-video-search --location eastus2. 创建 Azure OpenAI Service 资源az cognitiveservices account create --name semantic-video-openai --resource-group semantic-video-search \ --location eastus --kind OpenAI --sku s03. 获取端点与密钥az cognitiveservices account show --name semantic-video-openai \ --resource-group semantic-video-search | jq -r .properties.endpoint az cognitiveservices account keys list --name semantic-video-openai \ --resource-group semantic-video-search | jq -r .key14. 部署所需模型需要部署两个模型text-embedding-ada-002版本2或更高部署名同为text-embedding-ada-002gpt-5-mini部署名gpt-5-mini用于说话人抽取与摘要生成。az cognitiveservices account deployment create \ --name semantic-video-openai \ --resource-group semantic-video-search \ --deployment-name text-embedding-ada-002 \ --model-name text-embedding-ada-002 \ --model-version 2 \ --model-format OpenAI \ --scale-settings-scale-type Standard az cognitiveservices account deployment create \ --name semantic-video-openai \ --resource-group semantic-video-search \ --deployment-name gpt-5-mini \ --model-name gpt-5-mini \ --model-format OpenAI \ --sku-capacity 100 \ --sku-name Standard部署名--deployment-name就是后续环境变量AZURE_OPENAI_MODEL_DEPLOYMENT_NAME要填的值脚本通过部署名而非模型名调用模型务必保持一致。四、软件要求与环境变量1. 软件要求Python 3.9 或更高版本Git 客户端用于克隆外部示例仓库本文场景下可直接使用本仓库的 scripts 目录无需额外 cloneAzure CLI创建资源阶段使用。2. 环境变量运行转录准备脚本需要以下四个环境变量依据原文档及 requirements.txt 对应脚本源码环境变量含义读取位置AZURE_OPENAI_API_KEYAzure OpenAI Service API 密钥各 enrich 脚本AZURE_OPENAI_ENDPOINTAzure OpenAI Service 端点各 enrich 脚本AZURE_OPENAI_MODEL_DEPLOYMENT_NAME对话模型部署名默认gpt-5-minispeaker / summaries 脚本GOOGLE_DEVELOPER_API_KEYGoogle 开发者 API 密钥YouTube Data API v3transcript_download.pyWindows 下配置原文档建议写入用户环境变量。操作路径为Windows 开始菜单 编辑系统环境变量 环境变量 [USER] 的用户变量 新建AZURE_OPENAI_API_KEY \your Azure OpenAI Service API key AZURE_OPENAI_ENDPOINT \your Azure OpenAI Service endpoint AZURE_OPENAI_MODEL_DEPLOYMENT_NAME \your Azure OpenAI Service model deployment name GOOGLE_DEVELOPER_API_KEY \your Google developer API keyLinux / macOS 下配置建议追加到~/.bashrc或~/.zshrcexport AZURE_OPENAI_API_KEYyour Azure OpenAI Service API key export AZURE_OPENAI_ENDPOINTyour Azure OpenAI Service endpoint export AZURE_OPENAI_MODEL_DEPLOYMENT_NAMEyour Azure OpenAI Service model deployment name export GOOGLE_DEVELOPER_API_KEYyour Google developer API key需要补充的是从源码看还存在两个可选环境变量不设置时脚本会使用默认值AZURE_OPENAI_EMBEDDINGS_DEPLOYMENTEmbedding 模型部署名默认text-embedding-ada-002见 transcript_enrich_embeddings.pyAZURE_OPENAI_MODEL_DEPLOYMENT_NAME若不设置默认取gpt-5-mini见 transcript_enrich_speaker.py。此外enrich 系列脚本在启动时会调用dotenv.load_dotenv()因此也可以在脚本所在目录放一个.env文件来加载这些变量便于本地开发。五、安装 Python 依赖在 scripts 目录下创建并激活 Python 虚拟环境Windowspython -m venv .venv .venv\Scripts\activate pip install -r requirements.txtmacOS / Linuxpython3 -m venv .venv source .venv/bin/activate pip3 install -r requirements.txtrequirements.txt 中的关键依赖及其用途如下依赖版本约束用途openai1.54.0,2.0.0调用 Azure OpenAI 的 Responses API 与 Embeddings APIgoogle-api-python-client2.98.0,3.0.0调用 YouTube Data API v3 获取播放列表视频元数据youtube-transcript-api0.6.1,1.0.0抓取单条视频的字幕/转录tiktoken0.8.0,1.0.0估算文本 token 数量用于分桶与截断判断pandas2.1.0,3.0.0后续搜索应用加载索引scikit-learn/scipy1.3.0 / 1.11.2相似度计算与数值运算matplotlib/plotly3.7.2 / 5.16.1结果可视化rich13.5.2,14.0.0命令行进度条展示tenacity8.2.3API 调用自动重试指数退避六、运行整条流水线环境就绪后直接运行启动脚本即可按顺序执行全部六个阶段。启动脚本中约定的转录目录为transcripts_the_ai_show分桶时长为 3 分钟。WindowsPowerShell.\prepare_transcripts_ai_show.ps1macOS / Linux./prepare_transcripts_ai_show.sh启动脚本的核心逻辑以 prepare_transcripts_ai_show.sh 为例为export TRANSCRIPT_FOLDERtranscripts_the_ai_show export TRANSCRIPT_BUCKET_MINUTES3 mkdir -p $TRANSCRIPT_FOLDER/output python3 transcript_download.py -f $TRANSCRIPT_FOLDER -p PLlrxD0HtieHi0mwteKBOfEeOYf0LJU4O1 python3 transcript_enrich_speaker.py -f $TRANSCRIPT_FOLDER python3 transcript_enrich_bucket.py -f $TRANSCRIPT_FOLDER -m $TRANSCRIPT_BUCKET_MINUTES python3 transcript_enrich_summaries.py -f $TRANSCRIPT_FOLDER python3 transcript_enrich_embeddings.py -f $TRANSCRIPT_FOLDER python3 transcript_enrich_lite.py -f $TRANSCRIPT_FOLDER最后两个 if 判断把生成的master_enriched.json改名为embedding_index_full_3m.json、master_enriched_lite.json改名为embedding_index_3m.json。PowerShell 版 prepare_transcripts_ai_show.ps1 逻辑完全相同只是目录创建与文件改名使用 PowerShell 语法。如果你只想处理自己的播放列表可以修改启动脚本中的-p参数播放列表 ID与TRANSCRIPT_FOLDER播放列表较长时也可以手动分步执行各个 Python 脚本以单独调试某一阶段。七、六个脚本的源码级剖析1. transcript_download.py批量下载转录入口脚本 transcript_download.py 负责两件事通过 Google YouTube Data API v3 拉取播放列表全部视频的元数据标题、描述、videoId逐页翻页直到取完nextPageToken判空每期视频写入videoId.json元数据文件通过youtube_transcript_api的YouTubeTranscriptApi.get_transcript(video_id)获取每期视频转录清理换行符后写入videoId.json.vtt虽然扩展名为.vtt实际内容是 JSON 数组每个元素含text、start、duration字段。性能与健壮性设计40 个线程并发处理任务队列PROCESSING_THREADS 40显著加快大批量下载已存在的转录文件会被跳过os.path.exists判断支持断点续跑转录获取失败仅记录日志并跳过不影响整体流程。2. transcript_enrich_speaker.py函数调用抽取说话人transcript_enrich_speaker.py 用 OpenAI 函数调用Function Calling从标题 描述 前 3 分钟转录中抽取说话人名单。定义get_speaker_name函数 schema声明返回speakers字段并以tool_choice{type: function, name: get_speaker_name}强制模型调用该函数调用client.responses.create()Responses API系统提示词要求模型从文本中抽取说话人姓名姓名通常少于 3 个词解析返回的function_call参数把speakers写入对应元数据文件的speaker字段文本预处理clean_text会去掉换行、、[inaudible]等噪音使用 tenacity 重试装饰器随机指数退避等待 610 秒最多重试 4 次且不重试BadRequestError这类错误重试无意义累计错误超过 100 时脚本直接退出。3. transcript_enrich_bucket.py按时长分桶切块transcript_enrich_bucket.py 把长转录切成适合检索与摘要的短段是本流水线中索引粒度的决策点默认分段时长SEGMENT_LENGTH_MINUTES 5但启动脚本通过-m 3覆盖为 3 分钟每段开头会注入说话人、标题、描述作为上下文前缀帮助后续摘要与检索理解段落语义使用 tiktoken 估算 token 数单段累计超过MAX_TOKENS 2048时强制开启新段——为下一步摘要生成预留约 1024 token 的输出空间源码注释明确说明重叠上下文设计新段开始时把当前段前 5%PERCENTAGE_OVERLAP 0.05的词追加到上一段末尾保证相邻段落语义连贯课程文档中约 20 个词重叠即由此而来每段记录start时间HH:MM:SS格式与seconds秒数供搜索应用回跳到视频对应位置输出为output/master_transcriptions.json。4. transcript_enrich_summaries.py逐段生成摘要transcript_enrich_summaries.py 读取分桶结果为每个段落生成权威风格摘要系统提示词要求你是视频 AI 助手请撰写权威的 60 词摘要避免以 This video 开头调用 Responses APImax_output_tokens512单次请求超时 30 秒若响应状态不是completed脚本会警告并建议增大MAX_TOKENS后重试tenacity 重试随机指数退避 1045 秒最多 20 次同样不重试BadRequestError单段失败时降级用原文作为摘要保证流水线不中断摘要写回每段的summary字段输出output/master_enriched.json覆盖前一步同名文件前注意顺序依赖。5. transcript_enrich_embeddings.py生成语义向量transcript_enrich_embeddings.py 是生成可检索向量的核心读取output/master_enriched.json对每段text调用 Embeddings APIclient.embeddings.create模型部署名取自AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT默认text-embedding-ada-002向量结果存入段的ada_v2字段1536 维若段内已存在ada_v2则跳过支持断点续跑文本先经normalize_text归一化压缩空白、清理../. .等噪音单段超过 8191 token 时直接跳过Embedding API 的输入上限6 线程并发处理tenacity 重试等待 630 秒、最多 20 次输出前按videoId 起始秒排序保证索引有序写入output/master_enriched.json。6. transcript_enrich_lite.py生成轻量索引transcript_enrich_lite.py 用一段极简的字典推导式删除每段的text与description字段只保留摘要、向量、时间戳、说话人等元信息生成output/master_enriched_lite.json。这样在只依赖摘要与向量做检索、或需要大幅缩减文件体积时使用课程实际下发的embedding_index_3m.json即属此形态。八、输出物与 embedding_index 的用途全部脚本运行完毕后transcripts_the_ai_show/output/目录下会得到文件生成阶段说明master_transcriptions.jsonbucket 阶段全部切块段含正文与时间戳master_enriched.jsonsummaries embeddings 阶段含摘要与ada_v2向量的完整索引master_enriched_lite.jsonlite 阶段去掉正文的轻量索引embedding_index_full_3m.json改名产物完整版索引的最终交付名embedding_index_3m.json改名产物轻量版索引的最终交付名课程中现成的索引文件存放在 08-building-search-applications/embedding_index_3m.jsonscripts 目录下另有一份副本覆盖 AI Show 频道截至 2023 年 10 月的转录。根据 08-building-search-applications/README.md 的说明搜索应用将索引加载进 Pandas DataFrame查询时先把用户问题用 Embedding API 向量化再对索引中每个段落向量计算余弦相似度按相似度降序返回最相关的文本段从而定位到视频中答案所在的时间点。为课程便利索引以 JSON 文件 DataFrame 形式承载而在生产环境中索引通常会存入向量数据库如 Azure AI Search、Redis、Pinecone、Weaviate 等以支撑更大规模的数据与实时更新。九、使用注意事项执行顺序敏感六个脚本是严格的前置依赖链下载 → 说话人 → 分桶 → 摘要 → 向量 → 精简跳过或调换顺序会导致输入文件缺失断点续跑需从对应阶段开始。播放列表 ID 与转录可用性-p指定的播放列表必须公开youtube-transcript-api对部分视频如关闭字幕、区域受限可能拉取失败脚本会静默跳过可通过--verbose开启调试日志查看原因。配额与成本摘要与向量化均按段计费长播放列表会产生大量 API 调用tenacity 重试在限流/超时场景下会自动退避但多次重试仍会消耗时间与配额。模型部署名一致性text-embedding-ada-002与gpt-5-mini的部署名必须与创建资源时一致并与环境变量对应Embedding 部署名如需自定义可通过AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT覆盖。Python 版本脚本依赖 Python 3.9并使用dict[str, str | float]等新式类型注解如 bucket 脚本的VttSegment请确保解释器版本满足要求。通过以上八个环节你就能用 scripts 目录下这套脚本为任意 YouTube 播放列表构建自己的语义搜索索引进而在第 08 课搜索应用中实现提问 → 定位视频片段的完整闭环。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考