intent-search
Get API Key
สารบัญเริ่มต้น

เริ่มต้น

เริ่มต้นใช้งาน

จากยังไม่มีบัญชี ถึงผลค้นหาแรกจาก backend ของคุณเอง — ผ่าน /v1 อย่างเดียว

  1. สมัครและสร้างชุดข้อมูล

    ชุดข้อมูลคือกล่องหนึ่งใบที่เก็บระเบียนของสิ่งหนึ่งอย่าง — แคตตาล็อกสินค้า คลังบทความ รายชื่อสาขา อย่างละชุด แต่ละชุดมีดัชนีของตัวเอง คะแนนและตัวเลขทุกตัวจึงนับจากข้อมูลของคุณเท่านั้น

    สมัครใช้งาน แล้วกดสร้างชุดข้อมูล ใส่แค่ชื่อ ไม่ต้องบอกว่าข้อมูลหน้าตาเป็นยังไง

  2. หยิบคีย์ที่ได้มาแล้ว

    ชุดข้อมูลออกคีย์ให้สองดอกตั้งแต่ตอนสร้าง ไปที่ คีย์ API ของชุดข้อมูลนั้น service คือดอกที่ส่งของเข้ามา ตั้งค่า และสั่งขึ้นดัชนีได้ เก็บไว้ที่เซิร์ฟเวอร์เท่านั้น ส่วน client คือดอกที่ค้นหาได้อย่างเดียว วางในหน้าเว็บได้

    .env ของ backend
    NS_KEY=nsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   # service key
    TypeScript
    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
    }
  3. ส่งระเบียนของคุณแบบที่มันเป็น

    ไม่ต้องแก้ให้เข้ารูปก่อน — ฟิลด์ที่ซ้อนกัน คอลัมน์ที่ไม่ได้ใช้ค้น ค่าที่ปนกันหลายชนิด เก็บไว้ครบและส่งกลับมาทั้งระเบียนตอนค้นเจอ

    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 ตัวช่วยข้างบนจึงโยนข้อผิดพลาดให้เอง
  4. ปรับว่าฟิลด์ไหนค้นได้ กรองได้ เรียงได้

    โครงเขียนเป็นความสามารถของแต่ละฟิลด์ ไม่ใช่ชนิดของเอนจิน — 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)
  5. ค้นด้วยความหมาย

    คุณไม่ต้องทำเวกเตอร์เอง — เปิดครั้งเดียว โมเดลอ่านทุกระเบียนให้ แล้วส่ง 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

  6. หน้าร้าน: ตัวกรอง คำแนะนำ และสินค้าใกล้เคียง

    ผลค้นหาทุกครั้งพกตัวกรองของชุดข้อมูลมาในคีย์ 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 คือหน้าสุดท้าย

    จากหน้าเว็บใช้ client key และตั้งที่อยู่ของหน้าเว็บด้วย PUT /v1/origins ก่อน · อ่านเรื่องคีย์ · GET /v1/suggest · POST /v1/similar

  7. หน้าร้านที่เรนเดอร์บนเซิร์ฟเวอร์

    เมื่อหน้าร้านถามจากเซิร์ฟเวอร์ ทุกคนที่เปิดหน้ามาถึงด้วย 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 — ดูส่วนแบ่งทั้งหมดที่ ข้อผิดพลาดและเพดาน