เริ่มต้น
intent-search
เสิร์ชที่เข้าใจภาษาไทยจริง และเข้าใจว่าคนถามอะไร — ต่อผ่าน HTTP เส้นเดียว ไม่ต้องดูแลดัชนีเอง
มันทำอะไรให้
คุณส่งระเบียนของคุณเข้ามาแบบที่มันเป็นอยู่ แล้วค้นมันด้วยคำ ด้วย vector หรือทั้งสองอย่างพร้อมกัน ฝั่งเราเก็บระเบียนเต็มไว้และส่งกลับมาให้ทั้งชิ้น — เอนจินเห็นเฉพาะฟิลด์ที่คุณบอกว่าค้นได้ ส่วนที่เหลือของระเบียนไม่เคยออกจากฐานข้อมูลของเราไปที่ไหน
ที่ต่างจากการต่อกับเสิร์ชเอนจินตรง ๆ คือ คุณไม่ต้องทำเวกเตอร์เอง ส่ง "mode": "hybrid" มาพร้อมคำค้นที่เป็นข้อความ แล้วเราแปลงคำถามเป็น vector ให้ก่อนถามเอนจิน ลูกค้าพิมพ์ “อยากดูเด็กลง” แล้วเจอเซรั่มลดริ้วรอย ทั้งที่ไม่มีคำว่าเด็กอยู่ในหน้าสินค้าเลย — หลังจากเปิด PUT /v1/vectors ครั้งเดียว
ทุกเส้นของ /v1
คีย์หนึ่งดอกผูกกับชุดข้อมูลเดียว ทุกเส้นจึงไม่ต้องบอกว่าชุดไหน — คีย์บอกแทนแล้ว · ทุกเส้นอยู่ใต้ https://api.intent-search.dev
ข้อมูล
- POST
/v1/documentsเพิ่มหรือเขียนทับระเบียนในชุดข้อมูลที่คีย์นี้ผูกอยู่ แล้วพักไว้จนกว่าจะเรียก sync - POST
/v1/documents/removeเอาระเบียนออกตาม id ทีละหลายตัว แล้วพักไว้จนกว่าจะเรียก sync - GET
/v1/documents/:idอ่านระเบียนเต็มตาม id และดูว่าฉบับนี้ขึ้นดัชนีแล้วหรือยัง - DELETE
/v1/documents/:idเอาระเบียนออกตาม id แล้วพักไว้จนกว่าจะเรียก sync - POST
/v1/syncส่งทุกอย่างที่เขียนหรือลบไว้และยังไม่ถึงดัชนี ในครั้งเดียว
ค้นหา
- POST
/v1/searchค้นระเบียนด้วยคำ ด้วยความหมาย หรือทั้งสองอย่าง พร้อมตัวกรองและจำนวนของแต่ละค่า - POST
/v1/similarระเบียนที่คล้ายระเบียนหนึ่ง — ด้วยความหมายเมื่อเปิดเวกเตอร์ ด้วยคำเด่นของมันเมื่อไม่ได้เปิด - GET
/v1/suggestเติมคำให้กล่องค้นหา ตั้งแต่ตัวอักษรแรก และสินค้าอันดับต้นในคำขอเดียวกัน - POST
/v1/filtersทุกตัวกรองที่ชุดข้อมูลนี้มี พร้อมทุกค่าและจำนวน ในคำขอเดียว - POST
/v1/filters/:fieldไล่ทุกค่าของตัวกรองแบบรายการทีละหน้า
ตั้งค่า
- GET
/v1/schemaฟิลด์ไหนค้นได้ กรองได้ เรียงได้ ฟิลด์ไหนเก็บไว้เฉย ๆ และมีระเบียนค้างอยู่เท่าไหร่ - PUT
/v1/schemaบอกว่าฟิลด์ไหนค้นได้ กรองได้ เรียงได้ — ลองดูผลก่อนด้วย dry_run - GET
/v1/synonymsกลุ่มคำที่ค้นคำไหนก็เจอทุกคำในกลุ่ม - PUT
/v1/synonymsแทนที่ทุกกลุ่มคำพ้องด้วยรายการนี้ - GET
/v1/originsรายชื่อ origin ที่ client key ของชุดข้อมูลนี้ใช้ค้นจากเบราว์เซอร์ได้ - PUT
/v1/originsแทนที่รายชื่อ origin ทั้งหมดด้วยรายการนี้ - GET
/v1/vectorsเปิดไว้หรือยัง พร้อมใช้หรือยัง และสร้างไปถึงไหน - PUT
/v1/vectorsให้โมเดลอ่านทุกระเบียนครั้งเดียว แล้ว `mode: "hybrid"` กับ `/v1/similar` ใช้ความหมายได้ - GET
/v1/categoriesรายการหมวดของคุณ และจัดระเบียนเข้าหมวดไปแล้วเท่าไหร่ - PUT
/v1/categoriesบอกชื่อหมวดของร้านคุณ แล้วระบบจัดทุกระเบียนเข้าหมวดด้วยโมเดล — ค้นและกรองด้วยหมวดได้
ให้ agent ทำแทน
สมัคร สร้างชุดข้อมูล แล้วส่ง service key ให้ agent พร้อมบอกให้อ่าน /llms.txt — เอกสารทุกหน้าในไฟล์ Markdown เดียว ลำดับงานตั้งแต่ส่งระเบียนจนถึงเปิดการค้นด้วยความหมาย และวิธีรอให้พร้อมโดยไม่ต้องมีคนดู
เขียนด้วย TypeScript? /docs/types.ts คือ type ของทุกคำขอและคำตอบของ /v1 ในไฟล์เดียว ไม่มี import และไม่มีโค้ดที่รัน — วางไว้ในโปรเจกต์แล้ว import type { V1 } ได้เลย ตัวอย่างทุกตัวในเอกสารนี้ถูกตรวจกับไฟล์นี้ทุกครั้งที่ build
สามคำขอ
# 1. ส่งระเบียนของคุณแบบที่มันเป็น — ครั้งแรกระบบอ่านแล้วตั้งโครงให้เอง
curl -X POST "https://api.intent-search.dev/v1/documents" \
-H "Authorization: Bearer $NS_KEY" \
-H "Content-Type: application/json" \
-d '{"documents":[{"id":"sku-1042","product_name":"เซรั่มวิตามินซี ลดริ้วรอย","brand":"Aurora","price":890}]}'
# 2. ส่งที่พักไว้เข้าดัชนี
curl -X POST "https://api.intent-search.dev/v1/sync" \
-H "Authorization: Bearer $NS_KEY" \
-H "Content-Type: application/json" \
-d '{}'
# 3. ค้นด้วยข้อความที่คนพิมพ์ ตรง ๆ
curl -X POST "https://api.intent-search.dev/v1/search" \
-H "Authorization: Bearer $NS_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"เซรั่ม"}'ยังไม่มีคีย์? เริ่มต้นใช้งาน พาไปทีละขั้นตั้งแต่สมัคร จนถึงค้นด้วยความหมาย
สิ่งที่เปลี่ยน
คำตอบที่เปลี่ยนรูปจนโค้ดที่เขียนไว้ก่อนต้องแก้ตาม ใหม่สุดก่อน
GET /v1/pinsปิดแล้วทั้ง
GETและPUTปักหมุดยังไม่เปิดใน phase นี้ และหมุดที่ตั้งไว้ถูกลบทั้งหมด ·POST /v1/searchที่ส่งpinnedมาได้400· ที่ต้องแก้: เลิกเรียก/v1/pinsและเอาpinnedออกจากคำค้นPOST /v1/searchผลแต่ละชิ้นไม่มี
"reached": trueแล้ว ใช้wordsแทน:typedคำที่พิมพ์เจอตรง ๆ ·compoundเจอเพราะคำที่ยาวกว่าซึ่งขึ้นต้นด้วยคำที่พิมพ์เท่านั้น (คือที่เคยเป็นreached: true) ·widenedคำที่พิมพ์ไม่เจออะไร ผลนี้มาจากคำถามที่กว้างกว่า · ไม่มีwordsเมื่อความหมายอย่างเดียวเจอ · ที่ต้องแก้: เปลี่ยนhit.reachedเป็นhit.words === "compound"POST /v1/filters/:fieldบนหน้าที่ไล่ด้วย
afterคีย์otherนับเฉพาะสิ่งที่อยู่หลังหน้านี้ เดิมรวมหน้าก่อน ๆ ไปด้วย · คีย์ใหม่other_valuesคือจำนวนค่าที่ยังเหลือ และnoteนับจากตัวนี้ · หน้าสุดท้ายไม่มีnextแล้ว เดิมได้nextแล้วหน้าถัดไปว่าง ·missingมาด้วยแล้ว · เรียงแบบvalueพร้อมsizeได้ค่าแรกตามลำดับไทยจริง · ที่ต้องแก้: หยุดไล่เมื่อไม่มีnextไม่ต้องรอหน้าว่าง และอ่านจำนวนค่าที่เหลือจากother_valuesไม่ใช่otherPOST /v1/searchตัวกรองวันที่ที่ร้านบันทึกไว้ส่งเฉพาะช่องที่มีสินค้า เดิมส่งช่องว่างระหว่างช่องแรกถึงช่องสุดท้ายด้วย · เลือกขั้นได้ครบ minute hour day week month quarter year แต่ต้องไม่เกิน 200 ช่อง และเมื่อสินค้าใหม่ดันให้เกินจะได้ 200 ช่องล่าสุดพร้อม
degraded.reason: "facet_buckets_capped"· ที่ต้องแก้: ถ้าวาดกราฟจากaggregationsของตัวกรองวันที่ ให้เติมช่องที่ว่างเองGET /v1/categoriesสินค้าที่ห่างทุกหมวดเกิน
min_score(ค่าเริ่มต้น 0.6) ไม่ถูกจัดเข้าหมวดไหน เดิมได้หมวดที่ใกล้ที่สุดเสมอ · ระเบียนนั้นไม่มีคอลัมน์หมวด ตัวกรองหมวดนับไว้ในmissingและprogress.unfitบอกจำนวน · ตั้งmin_scoreได้ในPUT /v1/categoriesและเปลี่ยนแค่ค่านี้ไม่ทำให้จัดหมวดใหม่ · ที่ต้องแก้: อย่าถือว่าทุกระเบียนมีหมวดGET /v1/documents/:idid ใน path ถูกถอดรหัสครั้งเดียวตามมาตรฐาน เดิมถอดสองครั้ง id ที่มี
%อ่านหรือลบไม่ได้ และDELETE /v1/documents/sku%2541ลบskuAผิดชิ้น · ใช้กับDELETE /v1/documents/:idและPOST /v1/filters/:fieldด้วย · ที่ต้องแก้: encode id ครั้งเดียวด้วยencodeURIComponentถ้าเคย encode สองครั้งเพื่อเลี่ยงปัญหานี้ ให้เอาครั้งที่สองออกPOST /v1/searchcounted_fromมาคู่กับcounted_overและบอกว่าตัวเลขในaggregationsนับจากอะไร:matchesระเบียนที่คำค้นเจอ ·wordsระเบียนที่ฝั่งคำของhybridเจอ ผลที่ตรงความหมายอย่างเดียวไม่ถูกนับ ·allทุกระเบียนในชุดข้อมูล สำหรับvectorไม่ใช่เฉพาะผล · การค้นด้วยความหมายที่ไม่ได้นับอะไรไม่มีcounted_overแล้ว เดิมได้ค่าเท่ากับtotal· ที่ต้องแก้: อ่านcounted_overเฉพาะเมื่อมี และดูcounted_fromก่อนขึ้นข้อความว่าตัวเลขนับจากอะไรPOST /v1/searchreachedออกจากbroadenedมาเป็นคีย์ของคำตอบเอง — เดิม{"query":"รองเท้า"}ที่เจอตรง ๆ สี่รายการก็ได้broadened: {"reached": [...]}มาด้วย ตอนนี้broadenedมีเฉพาะเมื่อคำที่พิมพ์ไม่เจออะไรเลย · ที่ต้องแก้: อ่านreachedแทนbroadened.reached· ข้อความ “ไม่พบผลที่ตรง” ที่ขึ้นเมื่อมีbroadenedถูกแล้วโดยไม่ต้องแก้POST /v1/searchansweredมากับทุกคำตอบ ทุกmode— เดิมมีเฉพาะmode: "auto"·reasonเพิ่มmode_askedและno_mode· ที่ต้องแก้: ถ้าเคยถือว่ามีansweredแปลว่าใช้autoให้ดูmodeที่ส่งไปเอง และอ่านanswered.byว่าตอบด้วยคำหรือความหมาย