奔阳科技 API 控制台

创建新账户

用户注册

用户名（3-32位）

密码（至少8位）

响应结果

注意：API Key 只在注册时返回一次完整内容，请立即复制保存！

等待请求...

个人信息

当前用户信息

点击获取信息...

修改密码

旧密码

新密码（至少8位）

等待...

API Key 管理

我的 API Keys

点击刷新加载...

创建新 Key

Key 名称

权限范围 (Scopes)

每分钟限制（次）

每日限制（次）

注意：完整 Key 只在此处显示一次，请立即复制！

等待...

API 对话测试

接口配置

API Key（X-API-Key）

接口

请求 Body（JSON）

响应结果

等待请求...

接口文档

基础信息

Base URL：http://agent.fzbykj.com/api

认证方式：JWT（Bearer Token）或 X-API-Key 请求头

认证接口（无需凭证）

POST/api/v1/auth/register用户注册

POST/api/v1/auth/login用户登录

POST/api/v1/auth/refresh刷新 Token

POST/api/v1/auth/logout退出登录

用户接口（需 Bearer Token）

GET/api/v1/user/profile获取个人信息

POST/api/v1/user/change-password修改密码

API Key 接口（需 Bearer Token）

GET/api/v1/keys列出所有 Key

POST/api/v1/keys创建新 Key

PATCH/api/v1/keys/{id}修改 Key

DELETE/api/v1/keys/{id}删除 Key

GET/api/v1/keys/{id}/logs调用日志

业务接口（需 X-API-Key）

GET/api/v1/chat/models需要 chat:read

POST/api/v1/chat/completions需要 chat:write

AI 地震智能体 · API 接入指南

0. 一句话说明

本服务对外提供与 OpenAI Chat Completions 完全兼容的接口。你不需要为它单独写客户端——把任意 OpenAI 风格的 SDK / 工具（OpenAI 官方 SDK、LangChain、各类大模型网关等）的「服务地址」指到本服务、模型名填 eq-agent 即可直接调用，支持流式输出。

它只回答地震相关问题（速报、预警、历史地震目录），所有数字来自真实数据库查询，不会编造。

1. 快速开始（最小示例）

把 BASE 换成你的服务地址（本机开发默认 http://localhost:18432）。

非流式 (一次性返回)

流式 (SSE 逐字返回)

curl http://localhost:18432/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{ "model": "eq-agent", "messages": [{"role": "user", "content": "最近福建有哪些地震？"}] }'

2. 基础信息

项	值	说明
协议	HTTP / JSON，兼容 OpenAI Chat Completions
服务地址（本机开发）	`http://localhost:18432`	后端端口 18432
服务地址（生产）	见下方「生产环境访问」	公网端口默认被云安全组挡住，需经隧道或 nginx 反代
对话端点	`POST /v1/chat/completions`	OpenAI SDK 里 base-url 填到 `http://<地址>:18432/v1`
模型列表端点	`GET /v1/models`	返回唯一模型 `eq-agent`
模型名	`eq-agent`	请求里 `model` 字段填这个；其实填任意值也能跑，响应会回显

3. 鉴权（可选）

服务端有一个鉴权开关，默认关闭——本机开发与内网调用可以不带任何凭证。

开启后（生产对公网开放时建议开启），所有 /v1/** 请求必须带请求头：

Authorization: Bearer <API_KEY>

<API_KEY> 是服务端在环境变量 API_KEY 里配置的值。
校验不通过返回 401，响应体为 OpenAI 风格的错误结构（见第 7 节）。
用 OpenAI SDK 时，把这个值填进 SDK 的 api_key 参数即可；若服务端没开鉴权，api_key 随便填一个非空字符串。

提示：服务端开关：application.yml 的 app.api-auth.enabled（环境变量 API_AUTH=true）+ app.api-auth.api-key（环境变量 API_KEY）。

4. 接口详解

4.1 POST /v1/chat/completions

请求体字段：

字段	类型	必填	说明
model	string	否	模型名，填 `eq-agent`；缺省也行
messages	array	是	完整对话历史，见下
stream	boolean	否	`true` 走 SSE 流式；缺省 `false` 一次性返回
user	string	否	借作会话标识，仅用于服务端问答留档归类，不影响对话本身

注意：其它 OpenAI 字段（temperature、top_p、n、max_tokens 等）会被安全忽略，不报错、也不生效（本服务为了答案稳定，温度等参数固定在服务端）。

messages 的每条消息结构：

{ "role": "user" | "assistant" | "system", "content": "文本" }

role: user / assistant：构成对话历史（见第 5 节多轮对话）。
role: system：会被服务端忽略。本服务始终用自己的内置规则，不接受外部覆盖。
content 目前只支持字符串；不支持 OpenAI 的多模态数组形式。

4.2 非流式响应（stream 缺省或 false）

标准 chat.completion 结构：

{ "id": "chatcmpl-1c860549054249c4adb7fb9573bfd5eb", "object": "chat.completion", "created": 1781612541, "model": "eq-agent", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "最近福建的地震……" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 } }

* 注意：usage 里的 token 数目前固定为 0（服务端未做统计）。

4.3 流式响应（stream: true）

Content-Type: text/event-stream，逐片下发，每一片是一行 data: 加一个 JSON。结构与 OpenAI 一致：

data:{"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1781612549,"model":"eq-agent","choices":[{"index":0,"delta":{"role":"assistant"}}]} data:{"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1781612549,"model":"eq-agent","choices":[{"index":0,"delta":{"content":"最近"}}]} data:{"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1781612549,"model":"eq-agent","choices":[{"index":0,"delta":{"content":"福建"}}]} data:{"id":"chatcmpl-xxx","object":"chat.completion.chunk","created":1781612549,"model":"eq-agent","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]} data:[DONE]

首片只带 delta.role = "assistant"。
中间片只带 delta.content（一段文字）；拼接起来即是完整答案。
收尾片 delta 为空对象 {} 且带 finish_reason: "stop"。
最后单独一行 data:[DONE] 表示结束。

4.4 GET /v1/models

返回服务支持的模型列表（只有一个）：

{ "object": "list", "data": [ { "id": "eq-agent", "object": "model", "created": 0, "owned_by": "earthquake-agent" } ] }

5. 多轮对话（重要）

本接口遵循 OpenAI 的无状态语义：服务端不在会话间保存上下文，你需要在每次请求的 messages 里把完整对话历史给全。

例如第二轮追问「那它的深度呢」，要把第一轮的问答也一起带上，模型才知道「它」指哪次地震：

{ "model": "eq-agent", "messages": [ { "role": "user", "content": "福建宁德柘荣 2026 年 5 月 3 日 11:46 那次地震多大？" }, { "role": "assistant", "content": "3.1 级。" }, { "role": "user", "content": "那它的深度呢？" } ] }

6. 各语言 / 工具接入示例

下例统一假设服务地址 http://localhost:18432，鉴权关闭（api_key 随便填）。开了鉴权就把 api_key 换成真实 Key。

Python (OpenAI)

Node.js (OpenAI)

LangChain (Python)

Python (Raw SSE)

Browser (fetch)

from openai import OpenAI client = OpenAI( base_url="http://localhost:18432/v1", # 注意带 /v1 api_key="not-needed", # 没开鉴权随便填；开了就填真实 API_KEY ) # 非流式 resp = client.chat.completions.create( model="eq-agent", messages=[{"role": "user", "content": "最近福建有哪些地震？"}], ) print(resp.choices[0].message.content) # 流式 stream = client.chat.completions.create( model="eq-agent", messages=[{"role": "user", "content": "用一句话解释地震预警盲区"}], stream=True, ) for chunk in stream: delta = chunk.choices[0].delta.content if delta: print(delta, end="", flush=True)

import OpenAI from 'openai' const client = new OpenAI({ baseURL: 'http://localhost:18432/v1', apiKey: 'not-needed', }) const stream = await client.chat.completions.create({ model: 'eq-agent', messages: [{ role: 'user', content: '最近福建有哪些地震？' }], stream: true, }) for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content || '') }

from langchain_openai import ChatOpenAI llm = ChatOpenAI( base_url="http://localhost:18432/v1", api_key="not-needed", model="eq-agent", ) # 流式 for chunk in llm.stream("历史上福建发生过几次 4 级以上地震？"): print(chunk.content, end="", flush=True)

import json import requests with requests.post( "http://localhost:18432/v1/chat/completions", headers={"Content-Type": "application/json"}, # 开了鉴权再加 Authorization: Bearer <key> json={ "model": "eq-agent", "stream": True, "messages": [{"role": "user", "content": "2026 年以来全球最大的地震是哪次？"}], }, stream=True, ) as r: for line in r.iter_lines(decode_unicode=True): if not line or not line.startswith("data:"): continue payload = line[len("data:"):].strip() if payload == "[DONE]": break delta = json.loads(payload)["choices"][0]["delta"].get("content") if delta: print(delta, end="", flush=True)

const resp = await fetch('http://localhost:18432/v1/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'eq-agent', stream: true, messages: [{ role: 'user', content: '最近哪里发生了地震？' }], }), }) const reader = resp.body.getReader() const decoder = new TextDecoder() let buf = '' while (true) { const { value, done } = await reader.read() if (done) break buf += decoder.decode(value, { stream: true }) let idx while ((idx = buf.indexOf('\n\n')) >= 0) { const line = buf.slice(0, idx).split('\n').find((l) => l.startsWith('data:')) buf = buf.slice(idx + 2) if (!line) continue const payload = line.slice(5).trim() if (payload === '[DONE]') break const delta = JSON.parse(payload).choices[0].delta.content if (delta) console.log(delta) } }

7. 错误与排查

现象	原因	处理
HTTP 401，响应 `{"error":{"message":"无效的 API Key",…}}`	开了鉴权但没带或带错 Key	加请求头 `Authorization: Bearer <正确 Key>`
HTTP 401，响应 `{"error":{"message":"服务端鉴权未正确配置…",…}}`	服务端开了鉴权却没配 Key	联系服务端在 `.env` 里补 `API_KEY`
回答「系统未配置大模型密钥…」	服务端没配 `DEEPSEEK_API_KEY`	联系服务端配置后重启
回答「抱歉，这个我不方便介绍 / 超出了我的范围」	生产默认开启了「问题过滤 / 自身信息保密」	这是预期行为：本服务只答地震问题，问无关或探查实现的问题会被礼貌拒答
连接被拒 / 超时（生产）	公网端口被云安全组挡住	见下方「生产环境访问」

401 错误结构（OpenAI 风格，便于现成客户端识别）：

{ "error": { "message": "无效的 API Key", "type": "invalid_request_error", "code": "invalid_api_key" } }

提示：调用出错时，服务端通常不会抛 HTTP 5xx，而是把错误说明作为正常回答内容返回（流式则作为一段 content 增量），方便前端直接展示。

8. 注意事项与边界

只答地震问题：本服务专注地震速报、预警、历史地震目录。生产环境默认开启问题过滤，与地震无关的问题会被礼貌拒答。
数字来自真实数据，不编造：查不到会如实说「数据中没有相关记录」。
数据范围：事件库为 2026 年 3~6 月的历史事件 + MQTT 实时新增；台网历史目录覆盖 2008-12 至 2026-06-09（之后不更新）。
无状态：多轮对话靠你在 messages 里给全历史，服务端不跨请求记忆（见第 5 节）。
usage token 数固定为 0：未做统计。
暂无限流：服务端目前没有调用频率限制，请自行控制并发与频率。
content 仅支持字符串：不支持多模态数组。

9. 生产环境访问

生产部署在腾讯云，公网 18432 端口默认被云安全组挡住（接口面向公网有风险，刻意如此）。如需对外提供 API：

服务端在 .env 里设 API_AUTH=true 并填一个足够随机的 API_KEY（开启鉴权）；
再放开端口或经 nginx 反代（建议加 HTTPS 与限流）；
调用方按第 3 节带上 Authorization: Bearer <API_KEY>。

在未对公网开放前，可通过 SSH 隧道把服务器的 18432 映射到本地再调用。

附录：内部接口（自带前端专用，第三方一般不用）

除上面的 OpenAI 兼容接口外，服务还有一组 /api/** 内部接口，供项目自带的网页前端使用，带服务端多轮记忆（按 sessionId 区分会话，无需每次给全历史）：

端点	说明
POST/api/chat	非流式问答，入参 `{question, sessionId?}`，出参 `{answer}`
POST/api/chat/stream	流式问答（SSE），逐片 `data:{"delta":"…"}`，末尾 `data:[DONE]`
GET/api/info	返回当前环境 `{env: "dev" \| "prod"}`

这组接口不受 /v1 的 API Key 鉴权约束（给同源前端用）。第三方集成请优先使用第 1~6 节的 OpenAI 兼容接口。

BY API 控制台

注册账户

创建新账户

用户注册

响应结果

个人信息

当前用户信息

修改密码

API Key 管理

我的 API Keys

创建新 Key

API 对话测试

接口配置

响应结果

接口文档

基础信息

认证接口（无需凭证）

用户接口（需 Bearer Token）

API Key 接口（需 Bearer Token）

业务接口（需 X-API-Key）

AI 地震智能体 · API 接入指南

0. 一句话说明

1. 快速开始（最小示例）

2. 基础信息

3. 鉴权（可选）

4. 接口详解

4.1 POST /v1/chat/completions

4.2 非流式响应（stream 缺省或 false）

4.3 流式响应（stream: true）

4.4 GET /v1/models

5. 多轮对话（重要）

6. 各语言 / 工具接入示例

7. 错误与排查

8. 注意事项与边界

9. 生产环境访问

附录：内部接口（自带前端专用，第三方一般不用）

BY API 控制台

注册账户

创建新账户

用户注册

响应结果

用户登录

账户登录

响应结果

个人信息

当前用户信息

修改密码

API Key 管理

我的 API Keys 刷新

创建新 Key

API 对话测试

接口配置

响应结果

接口文档

基础信息

认证接口（无需凭证）

用户接口（需 Bearer Token）

API Key 接口（需 Bearer Token）

业务接口（需 X-API-Key）

AI 地震智能体 · API 接入指南

0. 一句话说明

1. 快速开始（最小示例）

2. 基础信息

3. 鉴权（可选）

4. 接口详解

4.1 POST /v1/chat/completions

4.2 非流式响应（stream 缺省或 false）

4.3 流式响应（stream: true）

4.4 GET /v1/models

5. 多轮对话（重要）

6. 各语言 / 工具接入示例

7. 错误与排查

8. 注意事项与边界

9. 生产环境访问

附录：内部接口（自带前端专用，第三方一般不用）

我的 API Keys