# llm-basic-example

**Repository Path**: bytesifter/llm-basic

## Basic Information

- **Project Name**: llm-basic-example
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-18
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# llmapi-example

LLM API 使用示例项目 — 学习 OpenAI / Anthropic / LiteLLM API 用法。

## 前置条件

- Python >= 3.10
- [uv](https://docs.astral.sh/uv/)（包管理器）
- 有效的 API Key（OpenAI / DeepSeek / Qwen 等）

## 配置

1. 复制环境变量模板：

   ```bash
   cp .env.example .env
   ```

2. 编辑 `.env`，填入你的 API Key（至少填写一个厂商的 Key 即可使用对应模块）。

## 运行示例

所有模块支持两种运行方式：

```bash
# 方式一：通过子命令路由（推荐）
uv run python -m llmapi_example.openai chat         # 对话参数示例
uv run python -m llmapi_example.openai stream        # 流式输出
uv run python -m llmapi_example.openai tools         # 工具调用
uv run python -m llmapi_example.openai reasoning     # 推理模型
uv run python -m llmapi_example.openai raw-request   # HTTP 原始请求检查
uv run python -m llmapi_example.openai continuation  # 自动续写

# 方式二：直接运行具体模块
uv run python -m llmapi_example.openai.chat
uv run python -m llmapi_example.openai.stream
uv run python -m llmapi_example.openai.tools
uv run python -m llmapi_example.openai.reasoning
uv run python -m llmapi_example.openai.raw_request
uv run python -m llmapi_example.openai.continuation
```

## 可用模块

### OpenAI 核心

| 模块 | 功能 | 状态 |
|------|------|------|
| `openai.chat` | 对话参数演示：temperature / top_p / penalty / stop / seed / json 输出 | ✅ 可用 |
| `openai.stream` | 流式输出 + usage 获取 | ✅ 可用 |
| `openai.tools` | 工具调用（单工具 + 多工具） | ✅ 可用 |
| `openai.reasoning` | 推理模型 reasoning_content 提取（同步 + 流式） | ✅ 可用 |
| `openai.raw_request` | httpx 事件钩子查看原始 HTTP 请求/响应头 | ✅ 可用 |
| `openai.continuation` | 自动续写（max_tokens 截断时自动续写，支持推理模型） | ✅ 可用 |

### 兼容性展示

| 模块 | 功能 | 状态 |
|------|------|------|
| `compatible.vendor_switch` | 同一 prompt 对比 OpenAI / DeepSeek / Qwen 输出 | ✅ 可用 |
| `compatible.extra_body` | DeepSeek prefix / Qwen enable_search 等厂商特有参数 | ✅ 可用 |

### 使用模式

| 模块 | 功能 | 状态 |
|------|------|------|
| `patterns.pipeline` | Pipeline 模式：分类 → 提取 → 格式化 | ✅ 可用 |
| `patterns.dialogue` | 多轮对话 + 滑动窗口裁剪历史 | ✅ 可用 |
| `patterns.structured` | 结构化输出 + 自动重试 | ✅ 可用 |
| `patterns.tool_executor` | 代理循环：自动执行工具直到完成或达到最大调用数 | ✅ 可用 |

## 设计约定

- **B1 按能力平铺**: 一个 .py 文件对应一个独立能力，不共享代码以提高可读性
- **自包含示例**: 每个模块独立可执行，硬编码演示参数
- **对比演示**: 参数类示例展示多个值的效果（如 temperature=0 vs 0.7 vs 1.5）
- **双入口**: `python -m llmapi_example.openai <subcommand>` 和 `python -m llmapi_example.openai.<module>` 均可

## 开发

安装开发依赖：

```bash
uv sync --group dev
```

运行测试：

```bash
uv run pytest
```

运行集成测试（需要真实 API Key）：

```bash
uv run pytest --run-integration
```

运行 lint：

```bash
uv run ruff check
uv run mypy src/
```