Skip to content

armgit / andee

Public Imported from GitHub
0

Andee lives on your phone or Mac and uses any app like you do—no integrations, no root, any model; memory and passwords never leave your device | Andee 住进你的手机或 Mac,像你一样操作任何 App——无需集成、无需 Root、支持任意模型,记忆和密码绝不离开设备。

docs: Volcengine voice needs an entitled resource, not just a key

andee-official92dda1541b4b
diff --git a/README.md b/README.md
index 88ccce3..314d125 100644
--- a/README.md
+++ b/README.md
@@ -505,10 +505,35 @@ On-device** tab (**Voice provider** → Volcengine or Google), and then fill in
This is a separate service from Volcengine's, with its own terms and data handling.
For **Volcengine**, a [Volcengine Speech](https://www.volcengine.com/product/voice-tech) API key goes
in the **Volcengine API key** field; for **Google**, a Vertex Express key plus a GCP project *number*
-and a location. Without a key for whichever one is selected, ASR and TTS fail during the handshake,
-which surfaces as a **connect timeout** — the device looks like it has a network problem when what it
-has is a blank field. Everything else still works; it is just mute and deaf.
-Whichever you pick, the audio goes to that provider — see [DISCLAIMER.md](DISCLAIMER.md).
+and a location. Without a key for whichever one is selected, ASR and TTS are **refused at the
+handshake** — the server answers at once, and answers no (a blank or a revoked key is a 403), so the
+socket dies before a byte of audio is sent. That is a different failure from a **connect timeout**,
+which is what a host that never answers looks like; reading the first as the second sends you off to
+check the network when the field is simply empty.
+Everything else still works; it is just mute and deaf.
+
+**With Volcengine, a correct key is still not enough.** In the console, "the service is activated"
+and "calls against this resource are entitled" are two different statements, and the API only checks
+the second. A service that was just switched on is **post-paid (后付费)** — it works from
+Volcengine's own demo page on the website and is rejected from code — so the key is right, the field
+is filled in, and the turn still dies at the start. The switch is on the console's **开通管理** page
+(activation management): set that service to **prepaid / subscription (预付 / 预购)** and buy a
+streaming-ASR resource pack there. Their billing terms are theirs and change without telling us, so
+this file does not restate them — only where the switch is.
+
+**That failure has two shapes, and when it happens is the clue.** Either the handshake is refused
+outright — the connection dies at the very start of the turn, before a byte of audio has gone out,
+which is the shape a missing entitlement takes — or the socket does come up and the server returns
+an error frame carrying the entitlement code after the first request. The first is **not** a
+timeout, the second is not a key problem, and both surface as `ASR ws refused: …` or as a server
+error code. Neither message points at 开通管理, which is why it is written down here.
+
+**If the pack you bought is a different SKU, the 识别资源 ID row is the third cause.** It
+sits under the Volcengine key (`asr_resource_id`), defaults to `volc.bigasr.sauc.duration`
+(the by-duration pack) and is sent as the `X-Api-Resource-Id` header, so a by-concurrency
+pack (并发版) needs its own value there instead. Get it wrong and the symptom is
+indistinguishable from the two above: the key is fine, the call just fails. Leave that row
+alone unless you bought something other than the duration pack.
> **If you took the CodeFlying route in [Install](#install), both keys are already baked in.**
> ⚙ → **Backend** will show **CodeFlying** as the active tab; LLM, ASR, TTS and the long tail of
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 21ec8c0..b20339d 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -417,10 +417,28 @@ OpenAI 兼容端点(`llm_api_key`,中文界面默认 `https://api.deepseek.c
Google),再填该服务商的密钥。这是两个独立的服务,条款和数据处理各归各家。
选**火山**就填[火山引擎语音服务](https://www.volcengine.com/product/voice-tech)的 API Key;
选 **Google** 则要一把 Vertex Express Key,外加 GCP 的**项目编号**(不是项目名)和一个区域。
-选中的那家没填密钥,识别和合成就会在握手阶段失败,**表现为连接超时** —— 看着像网络坏了,
-其实是那一栏空着。其余功能照常,只是既听不见也说不出。
+选中的那家没填密钥,识别和合成会**在握手阶段被直接拒绝** —— 服务器是应答了的,答的是「不行」
+(key 空着或被吊销都是 403),连接在一个字节的音频发出去之前就断了。这和**连接超时**不是一回事,
+超时是一台根本不回话的主机才有的样子;把前一种读成后一种,就会跑去查网络,而那一栏其实只是空着。
+其余功能照常,只是既听不见也说不出。
不管你选哪家,音频都会发到那家 —— 见 [DISCLAIMER.zh-CN.md](DISCLAIMER.zh-CN.md)。
+**火山这边,key 填对了也还是不够。** 控制台里「服务已开通」和「这个资源已被授权调用」是两句话,
+API 只认后一句。刚开通的服务默认是**后付费**,它只能在火山官网的体验页里用,程序走 API 会被拒
+—— 于是 key 是对的、那一栏也填满了,这一轮照样死在开头。开关在控制台的**开通管理**页:把该服务
+改成**预付 / 预购**,并在那里买一个流式语音识别的资源包。火山的计费条款是他们的,而且会不打招呼
+就改,所以这里不复述条款内容,只写到开关在哪一页。
+
+**这种失败有两种形态,而它失败的时机本身就是线索。** 要么握手被直接拒绝 —— 连接在对话的一开始
+就断,一个字节的音频都还没发出去,资源没有授权通常是这一种;要么连接确实建起来了,第一次请求
+之后服务端回一个带授权错误码的错误帧。前一种**不是**超时,后一种也不是 key 错了,而两者都表现为
+`ASR ws refused: …` 或者一个服务器错误码。这两句提示都不会叫你去开通管理,所以这件事写在这里。
+
+**如果买的包是另一种 SKU,第三种原因在「识别资源 ID」那一行。** 它就在火山 key 下面
+(`asr_resource_id`),默认 `volc.bigasr.sauc.duration`(按时长计费的包),作为
+`X-Api-Resource-Id` 头发出去,所以买的是并发版(按并发计费)就得把这里换成对应的值。填错了,
+症状和上面两种分不出来:key 没问题,就是调不通。没买时长版以外的包,这一行就别动它。
+
> **如果你走的是[安装](#安装)里 CodeFlying 那条路,这两把 Key 都已经在安装包里了。**
> ⚙ → **后端**会直接显示 **CodeFlying** 这一 tab 为当前后端;LLM、ASR、TTS 以及海量第三方 API
> (AI 图片/视频/音乐生成、地理位置、天气、PDF、搜索、新闻、股票……)都走同一把 Key,由 CodeFlying
diff --git a/docs/getting-started.md b/docs/getting-started.md
index e821580..868b80c 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -29,6 +29,8 @@ The same order is summarized in the README’s [Provisioning order](../README.md
Open ⚙ on the ball and choose **Backend → On-device**. Enter an OpenAI-compatible endpoint and `llm_api_key`; the local brain cannot run without the brain key. If you installed a CodeFlying package, its **CodeFlying** backend is already configured instead. A voice key is optional for a first typed interaction, but voice input and spoken replies need the selected voice provider configured too.
+For the Volcengine voice provider, a key on its own is not enough. A service that shows as activated in the Volcengine console is **post-paid** by default, and that tier works only from the console's demo page in a browser: the app's own calls are refused even when the key is correct. On the console's **开通管理** (activation management) page, change the service to prepaid/subscription and buy a streaming-ASR resource pack there. Until that is done, voice fails at the very start of the turn — the handshake is refused before any audio is sent — or the connection does open and an error frame carrying an entitlement code comes back after the first request. Neither is a network problem. If you bought a by-concurrency pack rather than the by-duration one, also set **识别资源 ID** (ASR resource ID) to the value that pack uses; it defaults to `volc.bigasr.sauc.duration` and is sent as the `X-Api-Resource-Id` header.
+
Now tap the ball, type a simple request such as “What can you see on this screen?”, and send it. The ball should expand into the conversation card, answer, and return to the floating ball when it is done. This confirms the basic loop: the app is running, the brain is reachable, and the overlay is visible. Do not use a payment, messaging, or other consequential task as the first test.
## 4. If something fails, use Self-check
diff --git a/docs/getting-started.zh-CN.md b/docs/getting-started.zh-CN.md
index e5dcfa9..493fef0 100644
--- a/docs/getting-started.zh-CN.md
+++ b/docs/getting-started.zh-CN.md
@@ -29,6 +29,8 @@ APK 装到设备后,按下面四步进行:
点击悬浮球上的 ⚙,进入**后端 → 本机**。填入一个 OpenAI 兼容端点和 `llm_api_key`;没有大脑密钥,本机大脑无法运行。如果安装的是 CodeFlying 包,**CodeFlying** 后端已经配置好。第一次用文字互动时,语音密钥不是必需的;但语音输入和朗读回复需要配置所选语音服务商。
+火山语音服务这边,光有 key 不够。控制台里显示「已开通」的服务默认是**后付费**,而它只能在官网的体验页里用:程序走 API 会被拒绝,key 填对了也一样。要到控制台的**开通管理**页把该服务改成预付 / 预购,并在那里买一个流式语音识别的资源包。在这之前,语音会在这一轮的最开头就失败 —— 握手被直接拒绝,音频还没发出去;或者反过来,连接起来了,但第一次请求之后收到一个带授权错误码的错误帧。两种都不是网络问题。如果买的是并发版的包而不是时长版,还要把**识别资源 ID** 改成那个包对应的值;它默认是 `volc.bigasr.sauc.duration`,会作为 `X-Api-Resource-Id` 头发送。
+
现在点击悬浮球,输入一句简单的话,例如“你能看到这个屏幕上的什么?”,然后发送。悬浮球应该展开成对话卡片,返回答案,完成后再缩回悬浮球。这说明基本链路已经通了:应用在运行、大脑可连接、悬浮窗可见。第一次测试不要使用付款、发消息或其它有实际后果的任务。
## 4. 出问题时使用自检