1 line
9.0 KiB
JSON
1 line
9.0 KiB
JSON
{"repo": "ahamedzoha/pulse", "files": {"docs/dashscope-setup.md": {"1261f22b971cc9301aeb9ea40f35502c219ee085": {"t": 1785674216.2108538, "n": 8701, "h": "2982802038e28820", "c": "# Step 6 prerequisite — DashScope (Alibaba Cloud Model Studio) API Key\n\nPractical, current (2026) walkthrough to get the LLM + embeddings key Pulse needs for\nworker embeddings (Step 5) and the RAG endpoint (Step 6), and the `.env` values to set.\n\n> **Time:** ~10–15 min (longer if your account needs real-name/identity verification).\n\n---\n\n## 0. \"DashScope is gone / renamed\" — what's actually true\n\nIt wasn't deleted, just rebranded at the **console** layer. The naming is confusing, so:\n\n| Name you'll see | What it is |\n|-----------------|------------|\n| **DashScope** | The **API service** brand. Still the API name, still the `DASHSCOPE_API_KEY` env var, still the `sk-...` key format, still the `dashscope-intl.aliyuncs.com` endpoint. |\n| **Model Studio** | The **console/product** you log into to manage keys and models (English branding). |\n| **Bailian / 百炼** | The **same product**, Chinese branding. \"Model Studio\" == \"Bailian\". |\n| **Qwen / Tongyi Qianwen** | The **model family** (e.g. `qwen-plus`) you call through DashScope. |\n\n**Bottom line:** you create a *Model Studio API key*, drop it into `DASHSCOPE_API_KEY`, and keep\nthe `dashscope-intl.aliyuncs.com/compatible-mode/v1` base URL. Nothing in Pulse's code changes.\n\n---\n\n## 1. Pick the right region — International (Singapore)\n\nPulse is hard-wired to the **International** deployment, hosted in **Singapore**:\n\n```\nhttps://dashscope-intl.aliyuncs.com/compatible-mode/v1\n```\n\n> ### ⚠️ Region keys are NOT interchangeable\n>\n> A Singapore key only works on the Singapore endpoint; a Beijing key only on the China endpoint.\n> Mixing them gives `Invalid API-key` / `401`. Pulse uses **Singapore (International)**, so create\n> your key in that region.\n>\n> | Region | OpenAI-compatible base URL |\n> |--------|----------------------------|\n> | **Singapore (International)** ✅ Pulse default | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` |\n> | China (Beijing) | `https://dashscope.aliyuncs.com/compatible-mode/v1` |\n> | US (Virginia) | `https://dashscope-us.aliyuncs.com/compatible-mode/v1` |\n\n> ### ⚠️ Newer Singapore accounts get a workspace-scoped domain\n>\n> Some accounts (especially newer ones, with `sk-ws-...` keys) are issued a **workspace-scoped**\n> Singapore host instead of the shared `dashscope-intl` domain:\n>\n> ```\n> https://ws-<your-workspace-id>.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1\n> ```\n>\n> The console may show this URL ending in **`/api/v1`** — that's the *native DashScope* path and\n> **will 404 with Pulse's OpenAI SDK**. You must use the **`/compatible-mode/v1`** suffix on the\n> same host. Set the full URL in `DASHSCOPE_BASE_URL`.\n\n> ### ⚠️ Don't grab a \"Coding Plan\" key\n>\n> Alibaba also sells **Coding Plan** keys (format `sk-sp-...`) that only work on\n> `coding-intl.dashscope.aliyuncs.com`. That is **not** what Pulse wants. Create a **standard\n> Model Studio API key** (format `sk-...`) and use the `compatible-mode` endpoint above.\n\n---\n\n## 2. Create / log into a Model Studio account\n\n1. Go to the **Model Studio console**: <https://modelstudio.console.alibabacloud.com>\n2. Click **Login** (top-right) and sign up or sign in with your Alibaba Cloud account\n (email signup works; this is the **international** site, not aliyun.com).\n3. Confirm the region selector (top of the page / account area) is set to **Singapore**.\n\n> **Identity verification:** International accounts must complete **account verification** before\n> API calls succeed. If your first call returns an auth/permission error even with a valid-looking\n> key, finish verification in the console (Account → Real-name/Identity verification).\n\n---\n\n## 3. Enable Model Studio & note the free quota\n\n1. On first visit, accept any prompt to **activate / enable Model Studio** for your account.\n2. New accounts get a **free trial quota** (a batch of free tokens per model, valid for a limited\n window). That's plenty for this demo's embeddings + a few RAG queries.\n\n> No need to pre-purchase anything. If you exhaust free quota you can enable pay-as-you-go later.\n\n---\n\n## 4. Create the API key\n\n1. In the left sidebar, open **API Keys** (a.k.a. *API-Key* / *Key Management*).\n2. Click **Create API Key** (top-right).\n3. (Optional) add a description like `pulse-demo`.\n4. Copy the key immediately — format `sk-xxxxxxxx...`. You can reopen the page later to copy it again.\n\n→ `.env`: `DASHSCOPE_API_KEY`\n\n> Store it in `.env` only — never commit it. Pulse's `.gitignore` already excludes `.env`.\n\n---\n\n## 5. Fill in `.env`\n\n```bash\n# ── Alibaba Cloud DashScope / Model Studio (LLM + embeddings) ──\nDASHSCOPE_API_KEY=sk-your-real-key\nDASHSCOPE_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1\n\n# Embeddings — text-embedding-v3 maxes at 1024 dims; the schema is vector(1536),\n# so Pulse defaults to text-embedding-v4 (which supports 1536). Leave as-is.\nEMBED_MODEL=text-embedding-v4\nEMBED_DIMENSIONS=1536\n\n# LLM for RAG answers\nLLM_MODEL=qwen-plus\n```\n\nOnly `DASHSCOPE_API_KEY` is strictly required — the other three have these exact defaults baked\ninto the code, so you can omit them unless you want to change models.\n\n### Models Pulse uses\n\n| Purpose | Model | Notes |\n|---------|-------|-------|\n| Embeddings | `text-embedding-v4` | Supports 1536 dims (and 2048/1024/768/512/256/128/64) |\n| RAG answers | `qwen-plus` | Good balance of cost/quality; `qwen-max` for higher quality |\n\n> ### Why not `text-embedding-v3`?\n>\n> The original project notes said `text-embedding-v3` @ 1536 dims — but per Alibaba's current docs,\n> **v3 only supports 1024 / 768 / 512**. Only **v4** supports 1536. To keep the `vector(1536)`\n> schema, Pulse uses **v4**. If you'd rather use v3, set `EMBED_MODEL=text-embedding-v3` +\n> `EMBED_DIMENSIONS=1024` **and** change `event_embeddings.embedding` to `vector(1024)` in\n> `infra/postgres/init.sql` (then recreate the DB volume).\n\n---\n\n## 6. Verify the key\n\n### Embeddings (what the embed worker uses)\n\n```bash\ncurl -s https://dashscope-intl.aliyuncs.com/compatible-mode/v1/embeddings \\\n -H \"Authorization: Bearer $DASHSCOPE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\":\"text-embedding-v4\",\"input\":\"pulse smoke test\",\"dimensions\":1536,\"encoding_format\":\"float\"}' \\\n | head -c 200\n# → {\"object\":\"list\",\"data\":[{\"object\":\"embedding\",\"index\":0,\"embedding\":[ ...\n```\n\n### Chat (what the RAG endpoint uses)\n\n```bash\ncurl -s https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions \\\n -H \"Authorization: Bearer $DASHSCOPE_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\":\"qwen-plus\",\"messages\":[{\"role\":\"user\",\"content\":\"Say hi in 3 words\"}]}' \\\n | head -c 300\n```\n\n### End-to-end through Pulse\n\nWith a real key set, restart the API and the embed worker will populate vectors automatically:\n\n```bash\npnpm infra:up\npnpm dev:api\n# create/update a task via the Board (or curl), then:\ndocker compose -f infra/docker-compose.yml exec postgres \\\n psql -U pulse -d pulse -c \"SELECT content_text, (embedding IS NOT NULL) AS has_vec FROM event_embeddings ORDER BY created_at DESC LIMIT 5;\"\n# has_vec should now be 't'\n```\n\nBefore a real key is set, the worker stores `content_text` with a **NULL embedding** (text-only)\nand logs a warning — the pipeline still runs; vectors backfill on re-embed once the key works.\n\n---\n\n## Troubleshooting\n\n| Symptom | Cause / fix |\n|---------|-------------|\n| `401` / `Invalid API-key` | Key is from the wrong **region** (e.g. Beijing key on the intl endpoint) or has a typo. Recreate in Singapore. |\n| `InvalidApiKey` but key looks right | Account **verification** not finished. Complete identity verification in the console. |\n| `Model not found` / `model not exist` | Model name typo, or the model isn't enabled in your region. Use `qwen-plus` and `text-embedding-v4`. |\n| Embeddings return 1024-length vectors | You set `EMBED_MODEL=text-embedding-v3` (caps at 1024). Switch to v4 for 1536, or change the schema. |\n| `coding-intl` / `sk-sp-` errors | You created a **Coding Plan** key. Create a standard Model Studio key (`sk-...`) instead. |\n| `404` on `/embeddings` or `/chat/completions` | `DASHSCOPE_BASE_URL` ends in `/api/v1` (native DashScope path). Change the suffix to `/compatible-mode/v1` on the same host. |\n| Worker logs \"DashScope disabled (no API key)\" | `DASHSCOPE_API_KEY` is empty or still `sk-placeholder`. Set the real key and restart. |\n| `429` / throttling | Free-quota rate limit or quota exhausted. Wait, or enable pay-as-you-go. |\n\n---\n\n## Teardown\n\nAfter the demo:\n\n1. **Model Studio → API Keys →** delete the `pulse-demo` key.\n2. If you enabled pay-as-you-go, confirm there are no lingering charges in **Billing**.\n3. Remove `DASHSCOPE_API_KEY` from any shared `.env`.\n"}}}} |