generative-ai-for-beginners 转录数据准备流水线面向语义搜索嵌入索引的 Azure OpenAI 完整实战指南【免费下载链接】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 课“Building a Search Applications”中语义搜索演示的核心数据——AI Show 频道的 YouTube 转录嵌入索引——是由一组 Python 数据准备脚本离线生成的。本文以 08-building-search-applications/scripts/README.md 为骨架完整覆盖从创建 Azure OpenAI 资源、部署模型、配置环境变量到运行六步转录处理流水线的全部实操细节并逐一对应仓库中的真实源码scripts 目录帮你建立“文档操作步骤 → 底层脚本实现”的完整映射。读完后你将能够独立复现一条“视频转录 → 说话人抽取 → 分桶 → 摘要 → 向量化 → 精简索引”的语义搜索数据管道并理解每一步的工程取舍。一、这组脚本在课程中的定位与整体流水线第 08 课 Building a Search Applications 的目标是构建一个能回答“什么是 Jupyter Notebooks”这类问题、并返回视频中对应时间点链接的语义搜索应用。该课程直接提供了一份现成的嵌入索引 embedding_index_3m.json约 49 MB课程 Notebook 直接加载它即可不运行脚本也能完成课程。而本 README 讲解的正是这份索引背后的数据生产流水线把 YouTube 视频转录下载下来逐步富集说话人信息、3 分钟分桶、GPT 摘要和文本嵌入。三平台包装脚本 prepare_transcripts_ai_show.sh、prepare_transcripts_ai_show.ps1 和 prepare_transcripts_ai_show.bat 的头部注释给出了流水线的权威定义以 bash 版为例见 prepare_transcripts_ai_show.sh#L3-L9# 1. Download the transcripts from YouTube # 2. Enrich the transcripts with speaker information # 3. Enrich the transcripts into 3 minute buckets # 4. Enrich the transcripts with with OpenAI ChatGPT summaries # 5. Enrich the transcripts with embeddings # 6. Enrich the transcripts with lite embeddings - removes the text property流水线对应的六个 Python 脚本与职责如下步骤脚本职责关键输出1 下载transcript_download.py按播放列表拉取每个视频的元数据与 WebVTT 转录videoId.json、videoId.json.vtt2 说话人transcript_enrich_speaker.py用 OpenAI Functions 从前 3 分钟转录中提取说话人姓名回写videoId.json的speaker字段3 分桶transcript_enrich_bucket.py将转录切分为带时间戳的文本块output/master_transcriptions.json4 摘要transcript_enrich_summaries.py对每个文本块生成约 60 词摘要output/master_enriched.json5 嵌入transcript_enrich_embeddings.py为每个文本块生成 ada-002 向量1536 维回写master_enriched.json的ada_v2字段6 精简transcript_enrich_lite.py移除text/description字段产出轻量索引output/master_enriched_lite.json包装脚本通过两个环境变量控制全局行为prepare_transcripts_ai_show.sh#L12-L13export TRANSCRIPT_FOLDERtranscripts_the_ai_show # 所有中间产物与输出的根目录 export TRANSCRIPT_BUCKET_MINUTES3 # 文本桶的时长分钟决定最终索引名中的 3m适用前提README 声明脚本已在 Windows 11、macOS Ventura 与 Ubuntu 22.04及以上的最新发布版上测试最低要求 Python 3.9课程 08 课 README 中针对搜索应用本身则建议 Python 3.10 或更高。二、创建 Azure OpenAI 服务资源README 建议先将 Azure CLI 升级到最新版本以保证与 OpenAI 服务兼容。以下命令与原文档逐条一致全部可直接在 Cloud Shell 或本地终端复制执行。2.1 创建资源组以 East US 区域的semantic-video-search资源组为例。可以更改名称但若更换部署区域需先核对 Azure 官方模型可用性表不同区域开放的模型版本不同az group create --name semantic-video-search --location eastus2.2 创建 Azure OpenAI Service 资源az cognitiveservices account create --name semantic-video-openai --resource-group semantic-video-search \ --location eastus --kind OpenAI --sku s0--kind OpenAI指定资源类型为 OpenAI 服务--sku s0表示 S0标准价格层。2.3 获取 Endpoint 与 API Key这两个值稍后要写入环境变量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 .key1jq -r用于从 JSON 响应中提取纯文本字段。2.4 部署两个模型流水线依赖两个模型部署text-embedding-ada-002版本 2 及以上用于第 5 步向量化gpt-4o-mini用于第 2 步说话人抽取与第 4 步摘要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-4o-mini \ --model-name gpt-4o-mini \ --model-format OpenAI \ --sku-capacity 100 \ --sku-name Standard注意两个部署的差异嵌入模型通过--model-version 2锁定模型版本--scale-settings-scale-type Standard指定扩缩类型聊天模型未指定版本跟随最新可用版本而是用--sku-capacity 100与--sku-name Standard显式声明容量与 SKU。三、配置环境变量运行转录准备脚本需要以下四个环境变量README 原文档的完整清单变量名含义源码中的实际消费方AZURE_OPENAI_API_KEYAzure OpenAI 服务 API Keytranscript_enrich_speaker.py#L28、transcript_enrich_embeddings.py#L25 等AZURE_OPENAI_ENDPOINT服务 Endpoint同上AZURE_OPENAI_MODEL_DEPLOYMENT_NAME聊天模型部署名默认回退gpt-4o-minitranscript_enrich_speaker.py#L36-L38GOOGLE_DEVELOPER_API_KEYGoogle 开发者 Key供 YouTube Data API v3 使用transcript_download.py#L19Windows 上建议加入“用户”环境变量Windows 开始菜单→编辑系统环境变量→环境变量→用户变量→新建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或~/.zshrc中添加 exportexport 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从源码结构看第 5 步嵌入脚本还读取一个可选变量AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT未设置时回退到text-embedding-ada-002见 transcript_enrich_embeddings.py#L27-L29因此嵌入部署名与默认值不一致时需要额外配置它。另外各富集脚本通过dotenv.load_dotenv()如 transcript_enrich_summaries.py#L20加载.env文件所以用.env文件代替 shell 导出也是可行的替代方案。四、安装 Python 依赖与虚拟环境README 给出的安装流程确认已安装 git 客户端从终端窗口进入脚本所在目录README 原始写法是克隆配套示例仓库后再进入其data_prep目录本仓库已将同一批脚本内置于 08-building-search-applications/scripts/ 目录可直接cd进入该目录然后创建并激活虚拟环境、安装依赖。创建虚拟环境# Windows (PowerShell) python -m venv .venv .venv\Scripts\activate# macOS / Linux python3 -m venv .venv source .venv/bin/activate安装依赖pip install -r requirements.txt # Windowspip3 install -r requirements.txt # macOS / Linux本仓库的 scripts/requirements.txt 用上下界约束锁定了每个库的主版本与脚本代码的实际 import 一一对应依赖版本约束用途openai1.54.0,2.0.0调用 Azure OpenAIResponses / Chat / Embeddings APIgoogle-api-python-client2.98.0,3.0.0YouTube Data API v3枚举播放列表视频youtube-transcript-api0.6.1,1.0.0抓取并格式化视频 WebVTT 转录tiktoken0.8.0,1.0.0分桶阶段的 token 计数transcript_enrich_bucket.py#L44pandas/scipy/scikit-learn/matplotlib/plotly各自 2.x/1.x/1.x/3.x/5.x 区间数据分析与可视化支撑rich13.5.2,14.0.0各富集脚本的进度条Progresstenacity8.2.3所有 LLM 调用的指数退避重试五、运行转录数据准备脚本三平台的包装脚本逻辑完全等价设置TRANSCRIPT_FOLDER与TRANSCRIPT_BUCKET_MINUTES3、创建output目录、按序执行六个 Python 脚本、最后把产物重命名为带桶时长的索引文件。Windows.\prepare_transcripts_ai_show.ps1macOS 与 Linux./prepare_transcripts_ai_show.sh注意本 README 原文档的“Run”一节写的是transcripts_prepare.ps1/transcripts_prepare.sh而当前仓库中实际的包装脚本命名为 prepare_transcripts_ai_show.ps1 / prepare_transcripts_ai_show.sh / prepare_transcripts_ai_show.bat。以仓库内实际文件名执行即可二者内容一致。以 prepare_transcripts_ai_show.sh 为例核心执行段为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其中-p PLlrxD0HtieHi0mwteKBOfEeOYf0LJU4O1是微软 AI Show 频道的播放列表 ID-m 3将第 3 步的分桶时长固定为 3 分钟。脚本末尾按产物是否存在重命名输出prepare_transcripts_ai_show.sh#L25-L33output/master_enriched.json→output/embedding_index_full_3m.json含全文的完整索引output/master_enriched_lite.json→output/embedding_index_3m.json精简索引即课程使用的形态六、六步流水线的源码级拆解6.1 下载transcript_download.pytranscript_download.py 用googleapiclient以GOOGLE_DEVELOPER_API_KEY构建 YouTube v3 客户端L131-L133以MAX_RESULTS 50分页遍历playlistItems().list(...)通过nextPageToken循环直到无下一页L142-L160。所有视频项进入线程安全队列后由PROCESSING_THREADS 40个并发工作线程消费L26-L27、L166-L178。每个视频产出两个文件gen_metadata()写入videoId.json字段为speaker初始空串、title、videoId、descriptionL69-L83get_transcript()用YouTubeTranscriptApi.get_transcript(video_id)拉取带start/duration/text的转录段清洗\n后以 4 空格缩进 JSON 存为videoId.json.vttL86-L114。两个工程细节值得注意已存在.json.vtt的视频直接跳过使下载步骤天然幂等、可断点续跑转录不可用的视频静默记录 debug 日志而不中断整体流程。6.2 说话人抽取transcript_enrich_speaker.py这一步是课程名“Semantic Search with OpenAI Embeddings andFunctions中 Functions 的体现。transcript_enrich_speaker.py 声明了一个get_speaker_name函数工具L58-L71并通过 Responses API 以tool_choice{type: function, name: get_speaker_name}强制模型必须调用该函数输出结构化结果L115-L130。输入文本的构造见 L195视频标题 描述 前 3 分钟的转录SEGMENT_MIN_LENGTH_MINUTES 3L32get_first_segment()按start begin 3*60截断L153-L180系统提示词则引导“从标题中抽取说话人姓名姓名通常不超过 3 个词”。请求参数temperature0.0确定性抽取、max_output_tokens512、超时 60 秒。抽取得到的speakers字符串被回写到对应videoId.json的speaker字段L207-L210供后续分桶步骤拼入文本开头。6.3 分桶transcript_enrich_bucket.pytranscript_enrich_bucket.py 把每段转录切分为带startHH:MM:SS与seconds的文本块切分由时间和token 上限双条件驱动SEGMENT_LENGTH_MINUTES默认 5 分钟被包装脚本的-m 3覆盖为 3 分钟MAX_TOKENS 2048L19-L22。每个块的 token 数用tiktoken.encoding_for_model(gpt-4o-mini)精确计算L43-L44源码注释说明预留 token 空间是为了给下一步的摘要请求留量。每块文本的组装顺序为The speakers name is X. 标题 描述 逐句转录L117-L130。块与块之间通过PERCENTAGE_OVERLAP 0.05实现重叠——append_text_to_previous_segment()把新块开头约 5% 的词追加到上一块末尾避免句子在块边界被切断、保证搜索上下文平滑L84-L93。08 课 README 将这一机制描述为“约 20 词重叠”与代码实现的是同一设计意图。最终所有块写入output/master_transcriptions.jsonL229-L231。6.4 摘要transcript_enrich_summaries.pytranscript_enrich_summaries.py 读取master_transcriptions.json把每个块的text送入gpt-4o-mini可经AZURE_OPENAI_MODEL_DEPLOYMENT_NAME覆盖生成摘要。系统提示词要求“写一段权威的 60 词摘要避免以 ‘This video’ 开头”L85-L101参数为temperature0.7、top_p0.0、max_output_tokens512、超时 30 秒若响应状态不是completed会告警并退出L106-L113。摘要写回段的summary字段L154后脚本按(videoId, start 转秒)稳定排序保证同一视频内片段按时间排列L191-L203输出output/master_enriched.json。这就是“每个 3 分钟片段都有人类可读摘要”的来源——课程中搜索结果的摘要展示用的正是这个字段。6.5 向量化transcript_enrich_embeddings.pytranscript_enrich_embeddings.py 使用AzureOpenAI客户端api_version固定为2024-10-21L33-L37模型为text-embedding-ada-002可由AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT覆盖。对每段文本先经normalize_text()归一化空白与标点超过 8191 token 的超长文本直接跳过ada-002 单次输入上限附近的安全阈值L111调用embeddings.create后把 1536 维向量写入段的ada_v2字段并原地覆盖master_enriched.jsonL117-L126。这里有一处增量设计的证据处理前先检查段内是否已存在ada_v2有则直接跳过L104-L106意味着嵌入步骤可安全中断重跑已完成的片段不会重复计费。字段名ada_v2表明该索引格式经历了嵌入模型版本演进保留旧字段名可向前兼容历史索引。6.6 精简索引transcript_enrich_lite.pytranscript_enrich_lite.py 逻辑极简用列表推导式剔除每段的text与description字段L31-L36输出master_enriched_lite.json。保留的字段包括speaker、title、videoId、start、seconds、summary、ada_v2——恰好构成一份可被向量数据库直接导入的轻量记录。仓库中随课提供的 embedding_index_3m.jsonscripts 目录 中另有一份同内容副本就是这份“lite”产物首条记录形如{speaker: Seth Juarez, Josh Lovejoy, Sarah Bird, title: ..., videoId: ..., start: 00:00:00, seconds: 0, summary: ..., ada_v2: [0.0043573, ...]}与 lite 脚本的字段剔除规则完全吻合。6.7 贯穿全流程的可靠性工程三个富集脚本共享同一套“多线程 重试 熔断”模式重试所有 LLM 调用用tenacity装饰wait_random_exponentialstop_after_attempt说话人抽取最多 4 次transcript_enrich_speaker.py#L104-L108摘要最多 20 次、间隔 10–45 秒transcript_enrich_summaries.py#L77-L81嵌入最多 20 次、间隔 6–30 秒transcript_enrich_embeddings.py#L85-L89且retry_if_not_exception_type(BadRequestError)确保参数错误不浪费重试配额。并发度下载 40 线程、说话人抽取 10 线程、摘要 10 线程、嵌入 6 线程按每步 API 限流特征分别调优。熔断说话人与摘要步骤维护全局errors计数超过 100 条直接exit(1)如 transcript_enrich_speaker.py#L188-L190避免在凭据或配额失效时继续空转。七、产物形态与课程衔接跑完流水线后transcripts_the_ai_show/output/下会得到master_transcriptions.json分桶结果、embedding_index_full_3m.json含全文 摘要 向量的完整索引与embedding_index_3m.json精简索引。课程演示并不要求你实际跑这套脚本——08 课 README 明确说明“完成本课无需运行脚本嵌入索引已随课提供”随课文件 embedding_index_3m.json 会被课程 Notebook如 python/aoai-assignment.ipynb加载进 Pandas DataFrame对用户查询做向量编码后用余弦相似度在 3 分钟粒度片段上排序最终返回带?t秒数时间戳的 YouTube 链接——即上图中“can you use rstudio with azure ml?”查询命中的那样一条结果。需要强调的适用前提这套流水线绑定 Azure OpenAIAPI version2024-10-21的嵌入端点、openai1.54SDK 的 Responses/Embeddings 调用方式与 YouTube Data API v3运行一次会对整条播放列表产生真实的模型调用费用且依赖播放列表 ID 固定如果你的目标是学习课程本身直接复用仓库内置的embedding_index_3m.json是成本最低的路径本文第二至六节则是你复现或改造这条数据管道时的完整蓝图。【免费下载链接】generative-ai-for-beginners21 Lessons, Get Started Building with Generative AI项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai-for-beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考