# Docker 环境 LLM 调用 404 错误修复指南

## 问题描述

在 Docker 环境部署时，LLM 调用返回 404 错误：

```
HTTP Request: POST https://api.coze.cn/chat/completions HTTP/1.1 404 Not Found
```

## 根本原因

错误的 API 端点：
- **错误端点**: `https://api.coze.cn/chat/completions`（缺少 `/v1/`）
- **正确端点**: `https://api.coze.cn/v1/chat/completions` 或 `https://api.coze.cn/v1`

## 诊断步骤

### 1. 在 Docker 容器中运行诊断脚本

```bash
# 进入容器
docker exec -it <container_id> /bin/bash

# 运行诊断脚本
cd /workspace/projects
python scripts/diagnose_docker_env.py
```

### 2. 检查关键内容

诊断脚本会检查以下内容：
- ✅ SDK 版本
- ✅ 关键文件修改时间
- ✅ 代码是否包含 `new_context()`
- ✅ LLM 调用测试

## 修复方案

### 方案 1：更新代码和 SDK（推荐）

这是最彻底的解决方案，确保使用最新的代码和依赖。

```bash
# 在 Docker 容器中执行
cd /workspace/projects

# 1. 更新代码
git pull

# 2. 更新依赖
pip install --upgrade coze-coding-dev-sdk

# 3. 验证更新
pip show coze-coding-dev-sdk

# 4. 重启服务
exit
docker restart <container_id>
```

### 方案 2：设置环境变量

如果无法更新代码，可以通过环境变量指定正确的端点：

```bash
# 在 Docker 容器中
export COZE_API_ENDPOINT="https://api.coze.cn/v1"
```

或者在 `docker-compose.yml` 中添加：

```yaml
environment:
  - COZE_API_ENDPOINT=https://api.coze.cn/v1
```

### 方案 3：重新构建 Docker 镜像

如果以上方案都不行，重新构建镜像：

```bash
# 1. 拉取最新代码
git pull

# 2. 重新构建镜像
docker-compose build

# 3. 重启服务
docker-compose down
docker-compose up -d
```

## 验证修复

修复后，运行以下命令验证：

```bash
# 测试 LLM 调用
python scripts/test_llm_api.py

# 应该看到类似输出：
# ✅ 成功 - 默认
# ✅ 成功 - https://integration.coze.cn/api
```

## 关键代码检查

确保以下关键文件包含正确的代码：

### 1. `src/graphs/nodes/recognize_and_correct_node.py`

```python
# 必须包含
from coze_coding_utils.runtime_ctx.context import new_context

# 创建 LLM 客户端时使用
ctx = new_context(method="invoke")  # ✅ 正确
client = LLMClient(ctx=ctx)

# ❌ 不要使用旧的方式
# client = LLMClient(runtime.context)  # 可能导致认证错误
```

### 2. `src/graphs/nodes/doc_extract_node.py`

```python
# 必须包含
from coze_coding_utils.runtime_ctx.context import new_context

# 创建 LLM 客户端时使用
ctx = new_context(method="invoke")
client = LLMClient(ctx=ctx)
```

### 3. `src/main.py`

确保包含请求体验证：

```python
# 验证请求体不为空
if not body:
    return create_error_response(400, "请求体为空")
```

## 常见问题

### Q1: 更新代码后仍然失败？

**A**: 可能是缓存问题，尝试：

```bash
# 清理 pip 缓存
pip cache purge

# 重新安装
pip install --force-reinstall --no-cache-dir coze-coding-dev-sdk

# 重启服务
docker restart <container_id>
```

### Q2: 如何确认代码已更新？

**A**: 检查文件修改时间：

```bash
ls -l src/graphs/nodes/recognize_and_correct_node.py
ls -l src/graphs/nodes/doc_extract_node.py
```

修改时间应该是最近的。

### Q3: SDK 版本是多少？

**A**: 检查 SDK 版本：

```bash
pip show coze-coding-dev-sdk
```

确保版本是最新的（建议 >= 1.0.0）

## 技术支持

如果以上方案都无法解决问题，请收集以下信息联系技术支持：

1. SDK 版本号：
   ```bash
   pip show coze-coding-dev-sdk
   ```

2. 完整的错误日志：
   ```bash
   tail -100 /app/work/logs/bypass/app.log
   ```

3. Docker 镜像信息：
   ```bash
   docker images
   ```

4. 诊断脚本输出：
   ```bash
   python scripts/diagnose_docker_env.py > diagnose_output.txt
   ```

## 总结

**根本原因**：错误的 API 端点（缺少 `/v1/` 前缀）

**推荐解决方案**：更新代码和 SDK

**快速验证**：运行诊断脚本 `scripts/diagnose_docker_env.py`

**预期结果**：LLM 调用成功，返回 200 状态码
