Skip to content

Update README and HiAgent API guide with model list and examples #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Bigzhangbig wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update README and HiAgent API guide with model list and examples #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 121 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,15 @@
你梨居然上新了满血版的r1 671b模型!可喜可贺~
正愁找不到免费可靠的api吗?刚好来白嫖学校的!

### 本项目的核心价值

北京理工大学提供的 HiAgent (agent.bit.edu.cn) 和 iBit (ibit.yanhekt.cn) 平台虽然功能强大，但其官方 API 接口采用的是自定义协议（需处理会话创建、UserID 管理、特定 SSE 事件等），无法直接与通用的 OpenAI 客户端（如 NextChat, LobeChat, OpenAI SDK 等）对接。

**本项目的作用：**
- **协议转换**：将 BIT 自定义 API 转换为标准的 OpenAI Chat Completions API 协议。
- **无状态化**：自动管理上游会话的创建与销毁，用户只需发送 `messages` 列表。
- **即插即用**：支持流式输出、思维链（Reasoning）显示，完美适配主流 AI 客户端。

## 项目架构图

```
Expand Down Expand Up @@ -98,15 +107,18 @@ openai_ibit/
|-----------|------|--------|------|
| `BIT_USERNAME` | 是* | `""` | 北理工统一身份认证用户名，用于 iBit 平台登录 |
| `BIT_PASSWORD` | 是* | `""` | 北理工统一身份认证密码，用于 iBit 平台登录 |
| `AGENT_APP_KEY` | 是* | `""` | 智能体广场应用密钥，用于 DeepSeek-R1 模型 |
| `AGENT_VISITOR_KEY` | 是* | `""` | 智能体广场访客密钥，用于 DeepSeek-R1 模型 |
| `API_KEY` | 否 | `""` | API 访问密钥，设置后客户端需在请求头中携带 `Authorization: Bearer <API_KEY>` |
| `PRINT_STATISTICS_INTERVAL` | 否 | `30` | 统计信息打印间隔（秒），控制控制台输出调用统计的频率 |
| `HI_API_KEY` | 是* | `""` | **推荐**：HiAgent 平台官方 API Key（从“发布管理”获取） |
| `AGENT_APP_KEY` | 否 | `""` | HiAgent 应用密钥（旧模式，不推荐） |
| `AGENT_VISITOR_KEY` | 否 | `""` | HiAgent 访客密钥（旧模式，不推荐） |
| `API_KEY` | 否 | `""` | 本服务的 API 访问密钥，设置后客户端需在请求头中携带 |
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

API_KEY 的说明缺少实际需要携带的请求头格式；当前服务端校验逻辑要求 Authorization: Bearer <API_KEY>。建议在此处补充明确的 header 示例，避免用户按文档配置后仍然 403。

Suggested change
| `API_KEY` | 否 | `""` | 本服务的 API 访问密钥，设置后客户端需在请求头中携带 |
| `API_KEY` | 否 | `""` | 本服务的 API 访问密钥。设置后客户端必须在请求头中携带 `Authorization: Bearer <API_KEY>` |

Copilot uses AI. Check for mistakes.
| `PRINT_STATISTICS_INTERVAL` | 否 | `30` | 统计信息打印间隔（秒） |
| `TZ` | 否 | 系统默认 | 时区设置，推荐设置为 `Asia/Shanghai` |

> **官方文档**：有关 HiAgent (agent.bit.edu.cn) 的官方 API 调用方法及说明，请参阅 [HiAgent 开发者中心](https://agent.bit.edu.cn/platform/doc/)。

> **注意**：标记为 `是*` 的环境变量表示至少需要配置一组模型凭证：
> - **iBit 模型**：需要同时设置 `BIT_USERNAME` 和 `BIT_PASSWORD`
> - **DeepSeek-R1 模型**：需要同时设置 `AGENT_APP_KEY` 和 `AGENT_VISITOR_KEY`
> - **DeepSeek-R1 模型**：推荐设置 `HI_API_KEY`；也可使用旧模式 `AGENT_APP_KEY` + `AGENT_VISITOR_KEY`
>
> 如果两组凭证都未配置，程序启动时会报错。

Expand All @@ -124,7 +136,16 @@ docker run -d -p 8000:8000 --name OpeniBIT \
yht0511/open_ibit:latest
```

#### 2. 仅使用智能体广场 DeepSeek-R1 模型
#### 2. 仅使用智能体广场 DeepSeek-R1 模型（官方推荐）

```bash
docker run -d -p 8000:8000 --name OpeniBIT \
-e HI_API_KEY=你的HiAgent官方API密钥 \
-e TZ=Asia/Shanghai \
yht0511/open_ibit:latest
```

#### 3. 仅使用智能体广场 DeepSeek-R1 模型（旧模式）

```bash
docker run -d -p 8000:8000 --name OpeniBIT \
Expand All @@ -134,19 +155,18 @@ docker run -d -p 8000:8000 --name OpeniBIT \
yht0511/open_ibit:latest
```

#### 3. 同时使用两个模型
#### 4. 同时使用两个模型

```bash
docker run -d -p 8000:8000 --name OpeniBIT \
-e BIT_USERNAME=你的统一身份认证用户名 \
-e BIT_PASSWORD=你的统一身份认证密码 \
-e AGENT_APP_KEY=你的应用密钥 \
-e AGENT_VISITOR_KEY=你的访客密钥 \
-e HI_API_KEY=你的HiAgent官方API密钥 \
-e TZ=Asia/Shanghai \
yht0511/open_ibit:latest
```

#### 4. 启用 API 密钥保护
#### 5. 启用 API 密钥保护

```bash
docker run -d -p 8000:8000 --name OpeniBIT \
Expand All @@ -157,14 +177,13 @@ docker run -d -p 8000:8000 --name OpeniBIT \
yht0511/open_ibit:latest
```

#### 5. 完整配置示例
#### 6. 完整配置示例

```bash
docker run -d -p 8000:8000 --name OpeniBIT \
-e BIT_USERNAME=你的统一身份认证用户名 \
-e BIT_PASSWORD=你的统一身份认证密码 \
-e AGENT_APP_KEY=你的应用密钥 \
-e AGENT_VISITOR_KEY=你的访客密钥 \
-e HI_API_KEY=你的HiAgent官方API密钥 \
-e API_KEY=你想设置的api密钥 \
-e PRINT_STATISTICS_INTERVAL=60 \
-e TZ=Asia/Shanghai \
Expand All @@ -186,8 +205,9 @@ services:
environment:
- BIT_USERNAME=你的统一身份认证用户名
- BIT_PASSWORD=你的统一身份认证密码
- AGENT_APP_KEY=你的应用密钥 # 可选
- AGENT_VISITOR_KEY=你的访客密钥 # 可选
- HI_API_KEY=你的HiAgent官方API密钥 # 推荐
- AGENT_APP_KEY=你的应用密钥 # 旧模式可选
- AGENT_VISITOR_KEY=你的访客密钥 # 旧模式可选
Comment on lines +208 to +210
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

README 中 docker-compose 的 environment 列表缩进不一致（- HI_API_KEY... 等行多了缩进），这会导致 YAML 无法被正确解析。建议将 208-210 行与其他环境变量保持同级缩进（与 - BIT_USERNAME=... 对齐）。

Suggested change
- HI_API_KEY=你的HiAgent官方API密钥 # 推荐
- AGENT_APP_KEY=你的应用密钥 # 旧模式可选
- AGENT_VISITOR_KEY=你的访客密钥 # 旧模式可选
- HI_API_KEY=你的HiAgent官方API密钥 # 推荐
- AGENT_APP_KEY=你的应用密钥 # 旧模式可选
- AGENT_VISITOR_KEY=你的访客密钥 # 旧模式可选

Copilot uses AI. Check for mistakes.
- API_KEY=你想设置的api密钥 # 可选
- PRINT_STATISTICS_INTERVAL=30 # 可选
- TZ=Asia/Shanghai
Expand All @@ -212,6 +232,7 @@ pip install -r requirements.txt
```bash
export BIT_USERNAME=你的统一身份认证用户名
export BIT_PASSWORD=你的统一身份认证密码
export HI_API_KEY=你的HiAgent官方API密钥 # 使用 deepseek-r1 时推荐
export API_KEY=你想设置的api密钥 # 可选
```

Expand All @@ -233,7 +254,7 @@ python server.py
| 模型名称 | 说明 | 所需环境变量 |
|---------|------|-------------|
| `ibit` | iBit 平台 DeepSeek 模型 | `BIT_USERNAME`, `BIT_PASSWORD` |
| `deepseek-r1` | 智能体广场 DeepSeek-R1 模型 | `AGENT_APP_KEY`, `AGENT_VISITOR_KEY` |
| `deepseek-r1` | 智能体广场 DeepSeek-R1 模型 | `HI_API_KEY`（推荐）或 `AGENT_APP_KEY` + `AGENT_VISITOR_KEY`（旧模式） |

### 客户端对接示例

Expand Down Expand Up @@ -266,8 +287,92 @@ for chunk in response:
- **API Key**：你设置的 `API_KEY`（未设置则随意填写）
3. 选择模型 `ibit` 或 `deepseek-r1`

## 官方 HiAgent Agent API 直连调用（不经过本项目）

如果你希望直接调用 HiAgent 官方 Agent API（不走 OpenAI 协议转换），可按以下方式：

- **Base URL**：`https://agent.bit.edu.cn/api/proxy/api/v1`
- **鉴权 Header**：`Apikey: 你的_API_KEY`
- **调用流程**：先 `POST /create_conversation`，再 `POST /chat_query_v2`

### 1）创建会话

```bash
curl -X POST 'https://agent.bit.edu.cn/api/proxy/api/v1/create_conversation' \
-H 'Apikey: 你的_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"UserID":"test_user_01"}'
```

从响应中取 `Conversation.AppConversationID`。

### 2）发送查询

```bash
curl -X POST 'https://agent.bit.edu.cn/api/proxy/api/v1/chat_query_v2' \
-H 'Apikey: 你的_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"UserID":"test_user_01",
"AppConversationID":"上一步获取的ID",
"Query":"你好，请简述 DeepSeek-R1 的优势。",
"ResponseMode":"blocking"
}'
```

`ResponseMode` 可选：
- `blocking`：阻塞返回完整回答
- `streaming`：流式返回

### 3）Python 示例

```python
import requests

BASE_URL = "https://agent.bit.edu.cn/api/proxy/api/v1"
API_KEY = "你的_API_KEY"
USER_ID = "test_user_01"

headers = {
"Apikey": API_KEY,
"Content-Type": "application/json"
}

# 1. 创建会话
res_create = requests.post(
f"{BASE_URL}/create_conversation",
headers=headers,
json={"UserID": USER_ID}
)
conv_id = res_create.json().get("Conversation", {}).get("AppConversationID")

# 2. 发送查询
res_query = requests.post(
f"{BASE_URL}/chat_query_v2",
headers=headers,
json={
"UserID": USER_ID,
"AppConversationID": conv_id,
"Query": "你好，请问 HiAgent 平台支持哪些大模型？",
"ResponseMode": "blocking"
}
)

print(res_query.json().get("answer"))
```

更多参考：
- [HiAgent 开发者中心](https://agent.bit.edu.cn/platform/doc)
- [HiAgent OpenAPI 通用说明](https://agent.bit.edu.cn/platform/doc/api/hiagent-openapi-general-instructions)
- [智能体接口详细文档](https://agent.bit.edu.cn/platform/doc/api/agent-api-call/agent-api-documentation)

## 更新日志

## 2026.3.3更新
- README 新增“官方 HiAgent Agent API 直连调用”章节，补充 `create_conversation` + `chat_query_v2` 的调用流程。
- 增加官方 `curl` 与 Python 示例，便于不经过本项目时直接对接 HiAgent。
- 统一 `deepseek-r1` 的凭证说明：推荐 `HI_API_KEY`，同时保留 `AGENT_APP_KEY` + `AGENT_VISITOR_KEY` 旧模式说明。

## 2025.6.8更新
现在支持智能体广场的模型,设置环境变量`AGENT_APP_KEY`和`AGENT_VISITOR_KEY`即可使用。
默认模型名称:"deepseek-r1",ibit模型名称:"ibit"。
Expand Down
128 changes: 128 additions & 0 deletions hiagent_api_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,128 @@
# HiAgent API 调用指南

本指南详细介绍了如何使用北京理工大学 HiAgent 平台的 API 接口进行大模型对话调用。

---

## 1. 准备工作

在调用 API 之前，您需要获取以下凭证：

### 1.1 获取 API Key (Apikey)
1. 登录 [HiAgent 平台](https://agent.bit.edu.cn)。
2. 进入您创建或拥有的**智能体**。
3. 在页面右侧或菜单中点击 **“发布管理”** 或 **“API 调用”**。
4. 在“API 密钥”部分，创建一个永久或限时的密钥并复制。

### 1.2 获取 AppID
在智能体页面的 URL 中或“API 调用”页面的代码示例中可以找到 `AppID`（如 `d5akl1...`）。

Comment on lines +17 to +19
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

文档在“获取 AppID”一节要求读者获取 AppID，但后续接口说明与示例请求均未使用该字段，容易造成困惑。建议要么补充 AppID 在哪些接口/字段中需要使用，要么删除该小节以保持一致性。

Suggested change
### 1.2 获取 AppID
在智能体页面的 URL 中或“API 调用”页面的代码示例中可以找到 `AppID`（如 `d5akl1...`）。

Copilot uses AI. Check for mistakes.
---

## 2. 接口基本信息

- **Base URL**: `https://agent.bit.edu.cn/api/proxy/api/v1`
- **内容类型 (Content-Type)**: `application/json`
- **鉴权方式**: 在 HTTP Header 中添加 `Apikey`。

---

## 3. 核心调用流程

HiAgent 的对话调用分为两个阶段：**创建会话** 和 **发送查询**。

### 3.1 创建会话 (Create Conversation)
在开始对话前，必须先获取一个有效的会话 ID。

- **Endpoint**: `/create_conversation`
- **Method**: `POST`
- **请求参数 (JSON)**:
- `UserID` (string, 必填): 用户标识，建议使用随机 ID 或固定用户标识。
- **返回结果**: 包含 `AppConversationID`，用于后续对话。

### 3.2 发送查询 (Chat Query V2)
使用获取到的会话 ID 进行实际的大模型对话。

- **Endpoint**: `/chat_query_v2`
- **Method**: `POST`
- **请求参数 (JSON)**:
- `UserID` (string, 必填): 与创建会话时一致。
- `AppConversationID` (string, 必填): 上一步获取的 ID。
- `Query` (string, 必填): 您的提问内容。
- `ResponseMode` (string): `blocking` (阻塞返回完整结果) 或 `streaming` (流式返回)。

---

## 4. Python 调用示例

以下是一个完整的自动化脚本，演示了从创建会话到获取回答的全过程。

```python
import requests
import json

# --- 配置区 ---
BASE_URL = "https://agent.bit.edu.cn/api/proxy/api/v1"
API_KEY = "您的_API_KEY" # 替换为实际密钥
USER_ID = "test_user_01" # 自定义用户 ID

def hiagent_test():
headers = {
"Apikey": API_KEY,
"Content-Type": "application/json"
}

# 1. 创建会话
create_url = f"{BASE_URL}/create_conversation"
create_payload = {"UserID": USER_ID}

print("正在创建会话...")
res_create = requests.post(create_url, headers=headers, json=create_payload)
if res_create.status_code != 200:
print(f"创建会话失败: {res_create.text}")
return

conv_id = res_create.json().get("Conversation", {}).get("AppConversationID")
print(f"会话创建成功，ID: {conv_id}")

# 2. 发送对话请求
query_url = f"{BASE_URL}/chat_query_v2"
query_payload = {
"UserID": USER_ID,
"AppConversationID": conv_id,
"Query": "你好，请问 HiAgent 平台支持哪些大模型？",
"ResponseMode": "blocking"
}

print("正在等待模型响应...")
res_query = requests.post(query_url, headers=headers, json=query_payload)
if res_query.status_code == 200:
answer = res_query.json().get("answer")
print("
=== 模型回复 ===")
Comment on lines +101 to +102
Copy link

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

示例代码里的 print(" 被断行成了两行，当前片段不是合法的 Python（会触发 SyntaxError）。建议将分隔标题改为单行字符串或使用 \n 显式换行。

Suggested change
print("
=== 模型回复 ===")
print("\n=== 模型回复 ===")

Copilot uses AI. Check for mistakes.
print(answer)
print("================")
else:
print(f"请求失败: {res_query.text}")

if __name__ == "__main__":
hiagent_test()
```

---

## 5. 常见问题 (FAQ)
- **报错 `missing required parameter`**: 检查是否遗漏了 `AppConversationID` 或 `UserID`。
- **401 Unauthorized**: 检查 Header 中的 `Apikey` 是否正确，注意大小写（`Apikey` 而非 `api-key`）。
- **流式输出**: 如果需要流式响应，需设置 `ResponseMode: "streaming"` 并通过 `requests` 的 `stream=True` 迭代获取数据块。

---

## 6. 资料来源
- [HiAgent OpenAPI 通用说明](https://agent.bit.edu.cn/platform/doc/api/hiagent-openapi-general-instructions)
- [智能体接口详细文档](https://agent.bit.edu.cn/platform/doc/api/agent-api-call/agent-api-documentation)
- [HiAgent API 调用示例代码](https://agent.bit.edu.cn/platform/doc/api/hiagent-api-call-examples)
- [HiAgent 开发者中心](https://agent.bit.edu.cn/platform/doc)

---
*文档生成日期：2026年3月2日*
Loading
Loading