# taskfriend-openai-compat-lab

**Repository Path**: cloudzun/taskfriend-openai-compat-lab

## Basic Information

- **Project Name**: taskfriend-openai-compat-lab
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-20
- **Last Updated**: 2026-01-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TaskFriend LLM 工程师工具包

## 概览

TaskFriend 是一套围绕检索增强生成（RAG）和大语言模型（LLM）工作流的实践型学习环境。项目结合了可执行的 Jupyter Notebook、可复用的 Python 模块、可视化工具和精心整理的数据集，对应 “LLM Engineer Course”（原 “LMP-C01 LLM Engineer (Professional)”）课程，主角 TaskFriend 专注于任务管理与效率提升场景，并支持替换式 LLM 后端与文档知识库。当前默认走 OpenAI 兼容接口：聊天用 DeepSeek，嵌入用硅基流动（SiliconFlow）。

## 仓库结构

- `LLM-Engineer-Course/taskfriend/`：TaskFriend 核心模块，涵盖聊天循环、上下文管理、RAG 索引编排与评估工具。
- `LLM-Engineer-Course/functions/`：配套 Notebook 的辅助函数，提供绘图、HTML 表格、嵌入可视化、打分和流式 LLM 客户端等能力。
- `LLM-Engineer-Course/docs/taskfriend/`：TaskFriend 使用的 Markdown 知识库，构成 RAG 的原始语料。
- `LLM-Engineer-Course/resources/`：训练集、基准题库、示例脚本等数据资产。
- `LLM-Engineer-Course/config/`：环境变量加载脚本（支持 OpenAI 兼容 DeepSeek/SiliconFlow）。
- `LLM-Engineer-Course/*.ipynb`：12 篇课程 Notebook，串联整套实验路径。
- `requirements.txt`：项目依赖列表。
- `version-20251016.txt`：课程内容的版本标识。

## 运行前置条件

- Python 3.10 及以上版本。
- OpenAI 兼容接口所需的 Key：默认聊天使用 DeepSeek（`OAI_COMPAT_CHAT_*`），嵌入使用硅基流动（`OAI_COMPAT_EMBED_*`）。
- 推荐：Jupyter 或 VS Code（安装 Python 与 Jupyter 插件）以运行 Notebook。

## 环境搭建步骤

1. 创建虚拟环境（建议使用 Python 3.12，以满足 `ms-swift` 对 `numpy<2` 的依赖）：

   PowerShell（Windows）：
   ```powershell
   py -3.12 -m venv taskfriend
   # 若提示 “running scripts is disabled”，请先执行：
   Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
   & .\taskfriend\Scripts\Activate.ps1
   ```

   Linux/macOS（bash/zsh）：
   ```bash
   python3 -m venv taskfriend
   source taskfriend/bin/activate
   ```

2. 在仓库根目录安装依赖（先升级 pip，再安装 requirements）。`torch==2.9.1+cpu` 需要从官方 CPU 源获取，建议统一加上 `--extra-index-url https://download.pytorch.org/whl/cpu` 以避免意外挂载 CUDA 轮子：

   PowerShell（Windows）：
   ```powershell
   python -m pip install --upgrade pip
   pip install -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cpu
   ```

   Linux/macOS（bash/zsh）：
   ```bash
   python3 -m pip install --upgrade pip
   pip install -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cpu
   ```

   若在国内网络环境安装缓慢，可临时使用镜像（以清华源为例），同样加上 CPU 源（不会写入全局配置）：

   PowerShell（Windows）：
   ```powershell
   # 仅本次命令生效
   pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple
   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple --extra-index-url https://download.pytorch.org/whl/cpu
   ```

   Linux/macOS（bash/zsh）：
   ```bash
   # 仅本次命令生效
   pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple
   pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple --extra-index-url https://download.pytorch.org/whl/cpu
   ```

3. 进入课程目录以确保本地包可解析：

   PowerShell（Windows）：
   ```powershell
   Set-Location "LLM-Engineer-Course"
   ```

   Linux/macOS（bash/zsh）：
   ```bash
   cd LLM-Engineer-Course
   ```

4. 验证关键依赖（`ms-swift` 安装后导入名为 `swift` 的模块）：

   ```powershell
   python -c "import swift, ragas, torch, langchain_openai, llama_index"
   ```

5. 配置 OpenAI 兼容 Key（首次或需要轮换时执行）：

   PowerShell（Windows）：
   ```powershell
   python config\load_key.py
   ```

   Linux/macOS（bash/zsh）：
   ```bash
   python config/load_key.py
   ```

   脚本会写入 `Key.json` 并导出 `OAI_COMPAT_*` 环境变量（DeepSeek/SiliconFlow）。
   如需快速开始，可将模板复制为个人密钥文件后再填入 Key（请勿提交到仓库）：

   PowerShell（Windows）：
   ```powershell
   Copy-Item Key.json.temp Key.json
   ```

   Linux/macOS（bash/zsh）：
   ```bash
   cp Key.json.temp Key.json
   ```

### OpenAI 兼容提供方配置（DeepSeek & 硅基流动）

为实现“通用 OpenAI 兼容”的最小改动切换，本项目支持通过 `Key.json` 或环境变量注入以下通用键：

**Key.json 支持的键（存在即加载，不提交密钥）**
- Chat：
   - `OAI_COMPAT_CHAT_BASE_URL`（示例：`https://api.deepseek.com/v1`）
   - `OAI_COMPAT_CHAT_API_KEY`
   - `OAI_COMPAT_CHAT_MODEL`（示例：`deepseek-chat` 或 `deepseek-reasoner`）
- Embeddings：
   - `OAI_COMPAT_EMBED_BASE_URL`（示例：`https://api.siliconflow.cn/v1`）
   - `OAI_COMPAT_EMBED_API_KEY`
   - `OAI_COMPAT_EMBED_MODEL`（示例：`BAAI/bge-m3`）
- 通用：
   - `OAI_COMPAT_STREAMING`（`true|false`）
   - `OAI_COMPAT_TIMEOUT`（秒）、`OAI_COMPAT_MAX_RETRIES`

运行 `python config\load_key.py` 会自动读取并设置以上环境变量。Notebook 的第 1–2 格可加入：

```python
from config.load_key import load_key
load_key(confirmation=False)
# 下面继续原实验流程，无需修改调用代码
```

如不使用 Key.json，也可在 PowerShell 或 Linux/macOS shell 中设置环境变量（占位示例，不要提交密钥）：

PowerShell（Windows）：
```powershell
# Chat via DeepSeek
setx OAI_COMPAT_CHAT_BASE_URL https://api.deepseek.com/v1
setx OAI_COMPAT_CHAT_API_KEY <YOUR_DEEPSEEK_KEY>
setx OAI_COMPAT_CHAT_MODEL deepseek-chat

# Embeddings via SiliconFlow
setx OAI_COMPAT_EMBED_BASE_URL https://api.siliconflow.cn/v1
setx OAI_COMPAT_EMBED_API_KEY <YOUR_SILICONFLOW_KEY>
setx OAI_COMPAT_EMBED_MODEL BAAI/bge-m3

# Optional
setx OAI_COMPAT_STREAMING true
setx OAI_COMPAT_TIMEOUT 60
setx OAI_COMPAT_MAX_RETRIES 3
```

Linux/macOS（bash/zsh，当前会话有效，建议写入 shell rc 文件以持久化）：
```bash
# Chat via DeepSeek
export OAI_COMPAT_CHAT_BASE_URL=https://api.deepseek.com/v1
export OAI_COMPAT_CHAT_API_KEY=<YOUR_DEEPSEEK_KEY>
export OAI_COMPAT_CHAT_MODEL=deepseek-chat

# Embeddings via SiliconFlow
export OAI_COMPAT_EMBED_BASE_URL=https://api.siliconflow.cn/v1
export OAI_COMPAT_EMBED_API_KEY=<YOUR_SILICONFLOW_KEY>
export OAI_COMPAT_EMBED_MODEL=BAAI/bge-m3

# Optional
export OAI_COMPAT_STREAMING=true
export OAI_COMPAT_TIMEOUT=60
export OAI_COMPAT_MAX_RETRIES=3
```

### Base URL 提醒

- 默认聊天走 DeepSeek `https://api.deepseek.com/v1`；嵌入走硅基流动 `https://api.siliconflow.cn/v1`。
- 如需切换其他 OpenAI 兼容网关（私有/区域端点），仅需调整对应 `OAI_COMPAT_*` 环境变量；未设置时会回退到历史 DashScope 配置。

## 最小冒烟测试

在根目录激活虚拟环境并安装依赖后，执行：

PowerShell（Windows）：
```powershell
Set-Location "LLM-Engineer-Course"
python examples\smoke_test.py
```

Linux/macOS（bash/zsh）：
```bash
cd LLM-Engineer-Course
python examples/smoke_test.py
```

该脚本将验证：
- Chat（非流式与流式各一条）是否正常返回（OpenAI 兼容 DeepSeek）。
- RAG 查询是否能生成答案（使用默认知识库与相似度 Top-K=2）。
- Embeddings 相似度是否可计算（OpenAI 兼容 SiliconFlow；不再提供 DashScope 回退）。

## 构建与读取 TaskFriend RAG 索引

TaskFriend 依赖 LlamaIndex + OpenAI 兼容嵌入（默认 SiliconFlow）。默认从 `docs/taskfriend` 读取文档，并将索引持久化在 `knowledge_base/taskfriend`（首次使用时自动创建）。

```python
# 在 "LLM-Engineer-Course" 目录中执行
from taskfriend import rag

# 更新知识库后可重建索引
rag.reindex()

# 读取已持久化的索引并构建查询引擎
index = rag.load_index()
query_engine = rag.query_engine(index)
```

## 启动聊天界面

聊天循环支持直接调用 LLM 或通过 RAG 包装。`functions/llm_utils.py` 已封装 OpenAI 兼容流式接口（默认 DeepSeek），可直接套用。

```python
from taskfriend import chat, rag
from functions.llm_utils import get_qwen_stream_response

index = rag.load_index()
engine = rag.query_engine(index)

# 将流式 LLM 函数包装成聊天接口需要的签名
call_llm = chat.wrap_streaming_for_chat(get_qwen_stream_response)
conversation = []

chat.chat_interface(
    full_conversation=conversation,
    query_engine=engine,
    call_llm_fn=call_llm,
    use_context_window=True,
    context_window=2000,
    show_context_preview=False
)
```

可以通过 `use_context_window`、`show_truncated`、`summarize_dropped` 等参数观察 TaskFriend 如何裁剪长对话，上下文默认配置在 `taskfriend/config.py`。

## RAG 质量评估

`taskfriend/evaluation.py` 提供 `Evaluator` 类，集成 Ragas 与 OpenAI 兼容 LLM/Embedding，可对单轮问答或多模型对比打分。

```python
from taskfriend.evaluation import Evaluator
from taskfriend import rag

index = rag.load_index()
engine = rag.query_engine(index, streaming=False)
response = engine.query("TaskFriend 如何帮助缓解任务过载？")

scorecard = Evaluator().evaluate_result(
    question="TaskFriend 如何帮助缓解任务过载？",
    response=response,
    ground_truth="TaskFriend 会引导你重新评估优先级并制定行动计划。"
)
print(scorecard)
```

也可以传入自定义模型/嵌入配置，使用 `compare_models` 与 `compare_embeddings` 对比不同组合的表现。

## 课程 Notebook 实验路线图

12 篇 Notebook 构成由浅入深的学习旅程，相互衔接如下（01–07 已全部适配至 OpenAI 兼容 DeepSeek/SiliconFlow，原有报错与缺失功能已修复）：

- **00 Setting Up the Environment**：完成本地/云端环境配置、依赖安装与 DashScope Key 管理，为后续实验打下基础。
- **01 The LLM Architecture**：回顾 LLM 基础原理、推理流程与部署形态，明确工具链为何物。
- **02 Creating Basic LLM Applications**：基于 00 配好的环境，实现最小可用的问答/对话应用，验证 API 调用链路。
- **03 Bridging Knowledge with RAG**：在 02 的应用上增加文档检索与向量索引，实现依赖知识库的问答。
- **04 Prompt Engineering for Success**：继续使用同一应用场景，系统梳理提示词设计与调优技巧，与 02/03 的代码形成闭环。
- **05 Evaluating RAG Performance**：引入 Ragas 等评估方法，量化 03 中 RAG 流水线的效果，并为 06 的优化提供基线。
- **06 RAG Optimization Techniques**：在 05 的指标基础上，尝试检索召回、重排、缓存等优化手段，对 RAG 作进一步提升。
- **07 Building Agentic AI Applications**：将 RAG 能力扩展到多工具/多阶段 Agent，复用前面构建的任务与评估模块。
- （可选）**08 Improving LLM Performance Through Fine-tuning**：探索微调途径，将 02/03 的应用接入调优后的模型，与未调优版本对比。
- （可选）**09 Deploying & Serving Your LLM App**：基于前面完成的应用，讨论部署、监控与扩缩容策略，与 07/08 的成果结合。
- **10 Best Practices for Developing & Deploying LLM Apps**：总结端到端流程的工程实践，包括团队协作、CI/CD、指标治理。
- **11 Building a Secure, Resilient AI Assistant**：在 09 的部署方案之上，强化安全、防护与高可用设计，形成全流程闭环。

整体来看，00–02 关注基础搭建，03–06 聚焦 RAG 构建与评估，07–09 延伸至 Agent 与上线阶段，10–11 则将工程规范与安全韧性纳入体系，确保学生能够贯通从原型到生产的完整链路。

## 常用工具模块

- `embedding_viz.py`、`vector_visualization.py`、`visualize_attention.py`：嵌入降维、相似度分析与注意力可视化。
- `metric_barchart.py`、`grader_plot.py`、`rag_eval_table.py`：评估指标可视化与对比图表。
- `html_table.py`：在 Notebook 中快速输出美观的 HTML 表格。
- `token_table.py`、`safe_token_str.py`：估算提示词 token 消耗、规避序列拼接错误。
### DashScope Base URL 提醒（仅聊天旧路径参考）

## 数据资产

- `docs/taskfriend`：TaskFriend 助手的核心知识源。
- 若继续使用 DashScope/Qwen 进行聊天，可参考其兼容端点：国内 `https://dashscope.aliyuncs.com/compatible-mode/v1`，国际 `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`。
- 当设置了 `OAI_COMPAT_CHAT_BASE_URL` 等通用变量时，聊天/评估将统一走 OpenAI 兼容路径（例如 DeepSeek）。
- 嵌入（Embeddings）路径已统一至 OpenAI 兼容提供方（SiliconFlow），不再提供 DashScope 回退。
- `resources/benchmark_exam.jsonl`：基准测试、考试或自动打分的题库。
- `resources/post.lua`：课程中用于拓展的 Lua 示例脚本。

## 开发提示

- 项目中的 RAG 与聊天模块都依赖 `DASHSCOPE_API_KEY` 环境变量，CI/CD 环境需要手动注入。
- 当启用上下文裁剪时，控制台会输出 ANSI 颜色日志；若终端不支持，可在 `taskfriend/utils.py` 中关闭彩色输出。
- 每次更新 `docs/taskfriend` 后请执行 `rag.reindex()` 刷新向量库。
- DashScope 在高并发时可能返回 429 限速，可在自动化评估时加上重试逻辑。
- 与 Notebook 配套的核心依赖（LlamaIndex、LangChain、Ragas 等）迭代频繁，建议保持 `requirements.txt` 指定的版本以避免 API 变更。

## 更多资料

- `docs/refactor/OpenAI-Compat-Quickstart.md`
- `docs/refactor/ProviderSwitch-Notes.md`
- `docs/refactor/Smoke-Test-Results.md`
- `docs/refactor/Progress-Update-2025-12-18.md`

## 切换到 OpenAI 兼容提供方（DeepSeek + SiliconFlow）

为统一 Chat 与 Embeddings 的配置，项目遵循通用 `OAI_COMPAT_*` 环境变量约定。Notebook 的“全局设置”单元格（第 5 格）示例如下（不再保留 DashScope Embeddings 回退）：

```python
# Set global settings (OpenAI-compatible only)
import os
import time
import logging
from pathlib import Path

from llama_index.core import Settings, VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms.openai_like import OpenAILike
from llama_index.embeddings.langchain import LangchainEmbedding
from langchain_openai import OpenAIEmbeddings

logging.getLogger().setLevel(logging.ERROR)

# Configure LLM via OpenAI-compatible provider (e.g., DeepSeek)
Settings.llm = OpenAILike(
   model=os.getenv("OAI_COMPAT_CHAT_MODEL", "deepseek-chat"),
   api_base=os.getenv("OAI_COMPAT_CHAT_BASE_URL"),
   api_key=os.getenv("OAI_COMPAT_CHAT_API_KEY"),
   is_chat_model=True,
)

# Configure Embeddings via OpenAI-compatible provider (e.g., SiliconFlow)
embed_base = os.getenv("OAI_COMPAT_EMBED_BASE_URL")
embed_key = os.getenv("OAI_COMPAT_EMBED_API_KEY")
embed_model_name = os.getenv("OAI_COMPAT_EMBED_MODEL")

if not (embed_base and embed_key and embed_model_name):
   raise ValueError(
      "Missing OAI_COMPAT_EMBED_* env vars. Please set EMBED_BASE_URL, EMBED_API_KEY, EMBED_MODEL."
   )

Settings.embed_model = LangchainEmbedding(
   OpenAIEmbeddings(
      model=embed_model_name,
      api_key=embed_key,
      base_url=embed_base,
   )
)

print("✅ Global parameters set! Chat: OpenAI-compatible; Embeddings: OpenAI-compatible")
```

- 依赖：确保安装 `llama-index` 与 `langchain-openai`（已在 `requirements.txt` 中列出）。
- 快速上手与完整示例请参见 [docs/refactor/OpenAI-Compat-Quickstart.md](docs/refactor/OpenAI-Compat-Quickstart.md)。