เริ่มต้น
เริ่มต้นใช้งาน
จากยังไม่มีบัญชี ถึงผลค้นหาแรกจาก backend ของคุณเอง — ผ่าน /v1 อย่างเดียว
สมัครและสร้างชุดข้อมูล
ชุดข้อมูลคือกล่องหนึ่งใบที่เก็บระเบียนของสิ่งหนึ่งอย่าง — แคตตาล็อกสินค้า คลังบทความ รายชื่อสาขา อย่างละชุด แต่ละชุดมีดัชนีของตัวเอง คะแนนและตัวเลขทุกตัวจึงนับจากข้อมูลของคุณเท่านั้น
สมัครใช้งาน แล้วกดสร้างชุดข้อมูล ใส่แค่ชื่อ ไม่ต้องบอกว่าข้อมูลหน้าตาเป็นยังไง
หยิบคีย์ที่ได้มาแล้ว
ชุดข้อมูลออกคีย์ให้สองดอกตั้งแต่ตอนสร้าง ไปที่ คีย์ API ของชุดข้อมูลนั้น
serviceคือดอกที่ส่งของเข้ามา ตั้งค่า และสั่งขึ้นดัชนีได้ เก็บไว้ที่เซิร์ฟเวอร์เท่านั้น ส่วนclientคือดอกที่ค้นหาได้อย่างเดียว วางในหน้าเว็บได้.env ของ backend NS_KEY=nsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # service keyTypeScript const NS = process.env.NS_URL ?? "https://api.intent-search.dev" async function ns(method: string, path: string, body?: unknown) { const r = await fetch(NS + path, { method, headers: { authorization: `Bearer ${process.env.NS_KEY}`, ...(body === undefined ? {} : { "content-type": "application/json" }), }, body: body === undefined ? undefined : JSON.stringify(body), }) const reply = await r.json() // ข้อผิดพลาดทุกตัวมีรูปเดียว: { "error": "ข้อความให้คนอ่าน" } if (!r.ok) throw new Error(`${method} ${path}: ${r.status} ${reply.error}`) return reply }ส่งระเบียนของคุณแบบที่มันเป็น
ไม่ต้องแก้ให้เข้ารูปก่อน — ฟิลด์ที่ซ้อนกัน คอลัมน์ที่ไม่ได้ใช้ค้น ค่าที่ปนกันหลายชนิด เก็บไว้ครบและส่งกลับมาทั้งระเบียนตอนค้นเจอ
TypeScript const products = [ { id: "sku-1042", product_name: "เซรั่มวิตามินซี ลดริ้วรอย", brand: "Aurora", price: 890, in_stock: true, raw: { supplier: "S-12", rank: 4 } }, { id: "sku-1043", product_name: "ครีมกันแดดเนื้อบางเบา SPF50", brand: "Aurora", price: 450, in_stock: false }, { id: "sku-2001", product_name: "กระถางต้นไม้ดินเผา ขนาดกลาง", brand: "Terra", price: 120, in_stock: true }, ]TypeScript // ครั้งละไม่เกิน 5,000 ระเบียน ส่งหลายครั้งได้ แล้ว sync ครั้งเดียว const written = await ns("POST", "/v1/documents", { documents: products }) // ครั้งแรก ระบบอ่านทั้ง batch แล้วบอกว่าตัดสินโครงไว้อย่างไร console.log(written.schema?.fields) // และทุกฟิลด์ว่าค่าที่ส่งมาเป็นชนิดอะไร กี่ค่าที่ไม่ได้ลงดัชนี console.log(written.report) // ทุกอย่างที่พักไว้ ขึ้นดัชนีพร้อมกันตรงนี้ const run = await ns("POST", "/v1/sync") console.log(`ส่งเข้าดัชนี ${run.sent} ระเบียน`)ครั้งแรกไม่ต้องตั้งโครงก่อน
ชุดข้อมูลที่ยังไม่มีโครง ระบบอ่านทั้ง batch แรกแล้วตัดสินให้ว่าฟิลด์ไหนค้นได้ กรองได้ เรียงได้ และตอบโครงนั้นกลับมาพร้อมรายงานชนิดข้อมูลของทุกฟิลด์ · ถ้าระเบียนของคุณใช้คอลัมน์อื่นเป็น id เช่นitemIdบอกก่อนเขียนครั้งแรกด้วยPUT /v1/schema {"id_field":"itemId"}ส่งแล้วยังค้นไม่เจอจนกว่าจะ sync
ของที่ส่งผ่าน/v1/documentsถูกพักไว้จนกว่าคุณจะเรียก/v1/syncเสมอ ระบบไม่เอาไฟล์ที่ยังส่งไม่จบขึ้นร้านให้เอง ·/v1/syncที่ล้มเหลวตอบ 502 ตัวช่วยข้างบนจึงโยนข้อผิดพลาดให้เองค้นหา
คำค้นเป็นข้อความธรรมดา ส่งสิ่งที่คนพิมพ์ในกล่องค้นหาไปตรง ๆ ได้เลย — ทุกคำต้องเจอ ภาษาไทยไม่ต้องเว้นวรรค และคำที่ยังพิมพ์ไม่จบก็เจอ
TypeScript const results = await ns("POST", "/v1/search", { query: "เซรั่ม", // ข้อความจากกล่องค้นหา ส่งตรง ๆ ได้เลย size: 20, }) for (const hit of results.hits) { // hit.document คือระเบียนเต็มของคุณ ทุกฟิลด์ รวม raw ที่ไม่ได้ลงดัชนี console.log(hit.document.product_name, hit.matched) }ปรับว่าฟิลด์ไหนค้นได้ กรองได้ เรียงได้
โครงเขียนเป็นความสามารถของแต่ละฟิลด์ ไม่ใช่ชนิดของเอนจิน —
searchพร้อมน้ำหนักfilterและsort·dry_runบอกก่อนว่าจะเปลี่ยนอะไร และต้องเขียนระเบียนใหม่หรือไม่TypeScript // ไม่ถูกใจโครงที่อนุมาน? เปลี่ยนได้โดยไม่ต้องส่งข้อมูลใหม่ const plan = await ns("PUT", "/v1/schema", { fields: [ { name: "product_name", type: "text", search: { weight: 3 } }, { name: "brand", type: "text", search: true, filter: { kind: "terms", label: "ยี่ห้อ" } }, { name: "price", type: "number", sort: true }, { name: "in_stock", type: "boolean", filter: true }, ], dry_run: true, // ดูก่อนว่าจะเปลี่ยนอะไร เอาออกเมื่อพร้อม }) console.log(plan.changes, plan.reindex)ค้นด้วยความหมาย
คุณไม่ต้องทำเวกเตอร์เอง — เปิดครั้งเดียว โมเดลอ่านทุกระเบียนให้ แล้วส่ง
mode: "hybrid"มากับคำค้นที่เป็นข้อความ ลูกค้าพิมพ์ “อยากดูเด็กลง” แล้วเจอเซรั่มลดริ้วรอยTypeScript // เปิดการค้นด้วยความหมาย ครั้งเดียวแล้วปล่อยไว้ — โมเดลอ่านทุกระเบียนให้เอง await ns("PUT", "/v1/vectors", { enabled: true }) // ระหว่างที่ยังสร้างไม่เสร็จ hybrid ได้ผลด้วยคำพร้อม degraded บอกว่ารออยู่ const meant = await ns("POST", "/v1/search", { query: "อยากดูเด็กลง", mode: "hybrid" }) console.log(meant.degraded?.reason ?? "ใช้ความหมายแล้ว")ระหว่างที่โมเดลยังอ่านไม่เสร็จ การค้นตอบด้วยคำตามปกติ และบอกเหตุผลในคีย์
degraded· ดูความคืบหน้าที่ GET /v1/vectorsหน้าร้าน: ตัวกรอง คำแนะนำ และสินค้าใกล้เคียง
ผลค้นหาทุกครั้งพกตัวกรองของชุดข้อมูลมาในคีย์
filtersและจำนวนของแต่ละค่าในaggregations·/v1/suggestเติมคำและให้สินค้าอันดับต้นในคำขอเดียว ·/v1/similarให้สินค้าใกล้เคียงของหน้าสินค้าหนึ่งชิ้นTypeScript // หน้าร้านหนึ่งหน้า: คำที่ลูกค้าพิมพ์ ตัวกรองที่ติ๊กไว้ และแถบเลขหน้า // ทุกอย่างอยู่ในเนื้อคำขอ — key บอกเองว่าเป็นชุดข้อมูลไหน // auto: ชื่อ ยี่ห้อ รหัส ตอบด้วยคำ ส่วนความต้องการตอบด้วยความหมาย นับโควตาเฉพาะครั้งนั้น const asked = { query: "Aurora", mode: "auto", filters: { brand: ["Aurora"] }, size: 1 } // pages คือเลขหน้าสุดท้ายที่แถบเลขหน้าจะชี้ไป (ตอบด้วยความหมายไม่มีเคอร์เซอร์ ใช้ from แทน) const page = await ns("POST", "/v1/search", { ...asked, pages: 5 }) console.log(page.answered.by, page.answered.reason) // words looks_like_a_name // จำนวนของแต่ละค่า นับจากคำค้นเดียวกับผล — วาดเป็นช่องติ๊กได้เลย for (const [field, counted] of Object.entries(page.aggregations ?? {})) { const values = (counted as { buckets: { key: string; count: number }[] }).buckets console.log(field, values.map((b) => `${b.key} (${b.count})`).join(", ")) } // แถบเลขหน้า: pages[k] คือ search_after ที่เริ่มหน้า k — เก็บไว้กับหน้าที่วาด แล้วส่งเมื่อถูกคลิก const pageCount = Math.ceil(page.total / asked.size) console.log(`มี ${pageCount} หน้า เคอร์เซอร์ถึงหน้า ${Object.keys(page.pages ?? {}).at(-1) ?? 1}`) if (page.pages?.["2"]) { const second = await ns("POST", "/v1/search", { ...asked, search_after: page.pages["2"] }) console.log(second.hits.map((hit: { id: string }) => hit.id)) } // ไปทีละหน้าก็ได้แบบเดิม: search_after จาก next · ไม่มี next คือหน้าสุดท้ายจากหน้าเว็บใช้
clientkey และตั้งที่อยู่ของหน้าเว็บด้วย PUT /v1/origins ก่อน · อ่านเรื่องคีย์ · GET /v1/suggest · POST /v1/similarหน้าร้านที่เรนเดอร์บนเซิร์ฟเวอร์
เมื่อหน้าร้านถามจากเซิร์ฟเวอร์ ทุกคนที่เปิดหน้ามาถึงด้วย key เดียวกันและจากเครื่องเดียวกัน — คนเดียวที่เปิดหลายแท็บจึงใช้อัตราของ key หมดแทนทุกคนได้ · ส่งหัวข้อ
X-End-Userพร้อม service key เป็น id ทึบของผู้เข้าชมหรือ IP ของเขา แล้วแต่ละคนได้ส่วนแบ่งหนึ่งในสี่ของอัตราของ key และแคชสั้น ๆ ตามคำขอทำให้หน้าที่ถูกเปิดซ้ำไม่ต้องถามใหม่TypeScript // หน้าร้านที่เรนเดอร์บนเซิร์ฟเวอร์: ทุกคนที่เปิดหน้ามาถึงด้วย key เดียวกันของเซิร์ฟเวอร์ // แคชสั้น ๆ ตามคำขอ — คำค้น ตัวกรอง และหน้า — หน้าที่ถูกเปิดซ้ำจึงไม่ต้องถามใหม่ const cache = new Map<string, { at: number; reply: any }>() const FRESH_MS = 30_000 async function searchFor(visitor: string, wanted: object) { const key = JSON.stringify(wanted) const kept = cache.get(key) if (kept && Date.now() - kept.at < FRESH_MS) return kept.reply const r = await fetch(NS + "/v1/search", { method: "POST", headers: { authorization: `Bearer ${process.env.NS_KEY}`, "content-type": "application/json", // ใครเป็นคนขอ: id ทึบของผู้เข้าชม หรือ IP ของเขา (ไม่ใช่อีเมล) // แต่ละคนได้หนึ่งในสี่ของอัตราของ key คนเดียวที่เปิดหลายแท็บจึงไม่ทำให้คนอื่นได้ 429 "x-end-user": visitor, }, body: JSON.stringify(wanted), }) const reply = await r.json() // ถูกบอกให้รอ แต่มีคำตอบเก่าอยู่ ส่งของเก่าไปก่อนดีกว่าหน้าว่าง if (r.status === 429 && kept) return kept.reply if (!r.ok) throw new Error(`POST /v1/search: ${r.status} ${reply.error}`) if (cache.size >= 500) cache.delete(cache.keys().next().value!) cache.set(key, { at: Date.now(), reply }) return reply } // ในตัวจัดการคำขอของเว็บ: IP ของผู้เข้าชม หรือ id ที่เก็บไว้ใน cookie // IP คือค่าแรกของ x-forwarded-for เมื่อเว็บอยู่หลัง proxy ที่คุณไว้ใจ ไม่อย่างนั้นคือ address // ของ socket ที่ต่อเข้ามา · ผู้เข้าชมปลอมค่านี้ได้ แต่คนที่ปลอมก็ได้แค่ส่วนแบ่งของตัวเอง // ตัวกรองที่ติ๊กและ search_after ของหน้าถัดไปอยู่ในคำขอเดียวกัน จึงเป็นส่วนหนึ่งของคีย์แคชด้วย const first = await searchFor("203.0.113.7", { query: "เซรั่ม", size: 20 }) const again = await searchFor("198.51.100.4", { query: "เซรั่ม", size: 20 }) console.log(first.total, again === first ? "จากแคช" : "ถามใหม่")client key ที่ส่ง
X-End-Userได้403— ดูส่วนแบ่งทั้งหมดที่ ข้อผิดพลาดและเพดาน