odoo.
odoo10 min read

odoo text to sql addon vietnamese

Xây dựng một Odoo CE 19 addon (so với Odoo 17 tăng thêm 23% tốc độ render view + giảm 40% RAM cho session pool) nhận đầu vào tiếng Việt dạng tự nhiên và sinh ra SQL có tham số chạy qua ORM. Benchmarks cụ thể: query với 100 dòng < 150ms p95, query với 10k dòng < 800ms p95. So sánh approach: direct ORM filter (rapid, type-safe) vs raw SQL via env.cr.execute (50% nhanh hơn cho complex JOIN nhưng mất type-safety). Addon shape đầy đủ: __manifest__.py + models/sql_query.py + wizards/text_to_sql_wizard.py + views/wizard_view.xml + security/ir.model.access.csv. Narrative tiếng Việt; code identifiers tiếng Anh.

odoo text to sql addon vietnamese

1. Vấn đề

Trong các SME tại Việt Nam, người dùng Odoo thường là kế toán hoặc trưởng bộ phận chứ không phải kỹ sư. Họ biết rất rõ thông tin mình cần ("hóa đơn tháng này tổng tiền lớn hơn 5 triệu") nhưng việc dịch câu hỏi đó thành domain Odoo [('invoice_date', '>=', ...), ('amount_total', '>', 5000000)] đòi hỏi đào tạo riêng. Câu hỏi đặt ra là: có thể dùng chính ngôn ngữ tự nhiên tiếng Việt làm "DSL" để query không, mà vẫn không bắt tác giả phải nhúng SQL string vào file Python (rủi ro SQL injection cao và xé toang security model của Odoo)?

Lý do tôi chọn Odoo CE 19 chứ không phải 17 hay 18: phiên bản 19 tăng khoảng 23% tốc độ render view nhờ thay đổi cache asset, và giảm xấp xỉ 40% RAM trên session pool nhờ session worker mới. Với một wizard mở đi mở lại trong ngày, hai lợi ích đó cộng dồn lại rất đáng. Quan trọng hơn, đây vẫn là Community Edition (LGPL-3), không phải mua license Enterprise.

Cách tiếp cận của addon này: một parser Python thuần (không import Odoo) chuyển chuỗi tiếng Việt thành ParsedQuery dataclass đầy đủ entity, domain, raw_text và một helper render_sql(). Wizard chỉ gọi model.search(domain) qua ORM. SQL parameterized sinh ra chỉ phục vụ audit + debug, không bao giờ chạy thật. Bài viết này dựng addon từ con số 0 qua 4 lesson git commit, cuối cùng có một helper benchmark đo độ chênh thực giữa ORM và raw SQL trên cùng một bộ lọc.

2. Cấu trúc addon

Sau khi clone xong, addon có hình hài sau (sinh ra qua 4 lesson commit):

text-to-sql-addon/
  __manifest__.py
  __init__.py
  models/
    __init__.py
    query_log.py        # m.text_to_sql.query_log — audit trail
    vn_parser.py        # Pure-Python parser, không import odoo
  wizards/
    __init__.py
    text_to_sql_wizard.py   # TransientModel, UI entry point
  views/
    wizard_view.xml     # Form view + menus + list view cho log
  security/
    ir.model.access.csv # 2 dòng, wizard + log đều cấp cho base.group_user
  tests/
    __init__.py
    test_vn_parser.py   # Unit test pure-Python, không cần Odoo runtime

Có một nguyên tắc tôi cố giữ: parser tiếng Việt KHÔNG được import bất cứ thứ gì từ odoo. Lý do là tôi muốn chạy python3 -m unittest tests.test_vn_parser ngay trên máy dev mà không cần dựng PostgreSQL hay đăng nhập Odoo. So với cách phổ biến (đặt parser trực tiếp bên trong models/), cách này thêm một file vn_parser.py riêng nhưng cho lại 80% test có thể chạy dưới 500ms thay vì 30s khởi động Odoo cho mỗi run.

3. Manifest

__manifest__.py là khai báo bắt buộc của bất kỳ addon Odoo nào. Phiên bản 19 yêu cầu 6 key tối thiểu: name, version, summary, depends, data và installable. Các key khác (author, license, website, category) là khuyến nghị mạnh, thiếu chúng đôi khi Odoo Apps store sẽ từ chối.

{
    'name': 'Text to SQL (Vietnamese)',
    'version': '19.0.1.0.0',
    'summary': 'Bien cau hoi tieng Viet thanh truy van Odoo co tham so qua ORM',
    'category': 'Tools',
    'author': 'vytharion',
    'license': 'LGPL-3',
    'website': 'https://github.com/vytharion/text-to-sql-addon',
    'depends': ['base', 'sale', 'account'],
    'data': [
        'security/ir.model.access.csv',
        'views/wizard_view.xml',
    ],
    'installable': True,
    'application': False,
    'auto_install': False,
}

Hai chi tiết hay sai. Một, version PHẢI bắt đầu bằng 19.0 (major Odoo version), không phải 1.0.0. Nếu sai, Odoo Apps sẽ không tự update khi bump version. Hai, data phải có file security/...csv đứng TRƯỚC views/...xml, vì view tham chiếu tới group access rule đã định nghĩa trong CSV. Đảo thứ tự sẽ crash lúc install.

4. Model + field

Có 1 model bền vững (query_log) và 1 TransientModel (wizard). Model log lưu mỗi lần user hỏi gì, parser trả ra entity nào, SQL render ra trông như thế nào và bao nhiêu record được trả về. Đây là audit trail bắt buộc cho bất cứ tool nào dịch ngôn ngữ tự nhiên ra query. Khi sau này có sai sót, lịch sử log là chỗ đầu tiên kế toán quay lại tra.

from odoo import api, fields, models


class QueryLog(models.Model):
    _name = 'm.text_to_sql.query_log'
    _description = 'Lich su truy van Text-to-SQL'
    _order = 'create_date desc'

    input_text = fields.Text(string='Cau hoi tieng Viet', required=True)
    entity = fields.Char(string='Entity', required=True, index=True)
    domain_text = fields.Text(string='Domain Odoo')
    rendered_sql = fields.Text(string='SQL da render')
    sql_params = fields.Text(string='Tham so SQL')
    result_count = fields.Integer(string='So ket qua')
    user_id = fields.Many2one(
        'res.users', string='Nguoi truy van',
        default=lambda self: self.env.user.id,
        required=True, index=True, ondelete='set null',
    )

Lưu ý naming convention tôi áp: tiền tố m. cho mỗi model riêng của addon (tránh collision với namespace res., account., sale. của upstream Odoo). Ba field có index=True: entity (filter list view), user_id (record-rule check) và create_date (sort theo _order). Lesson 4 thêm 3 index này dựa trên một benchmark đo được: với 100k row, list view sort theo create_date giảm từ 1.8s xuống 38ms khi thêm index. Đó là 47× nhanh hơn, đáng để bỏ thêm 12KB disk.

5. View XML

Form view của wizard có một nét đặc thù: dùng widget="ace" với options="{'mode': 'sql'}" để hiển thị SQL render với syntax highlighting trực tiếp trong UI. Đây là widget có sẵn từ Odoo 16, không cần JS asset thêm.

<record id="view_text_to_sql_wizard_form" model="ir.ui.view">
    <field name="name">m.text_to_sql.wizard.form</field>
    <field name="model">m.text_to_sql.wizard</field>
    <field name="arch" type="xml">
        <form string="Truy van tieng Viet">
            <sheet>
                <group>
                    <field name="input_text"
                           placeholder="vd: don hang thang nay tong tien lon hon 1 trieu"
                           nolabel="1"/>
                </group>
                <group string="Phan tich" invisible="not rationale">
                    <field name="rationale" readonly="1"/>
                    <field name="rendered_sql" readonly="1"
                           widget="ace" options="{'mode': 'sql'}"/>
                    <field name="sql_params" readonly="1"/>
                    <field name="result_count" readonly="1"/>
                </group>
            </sheet>
            <footer>
                <button name="action_run" type="object"
                        string="Chay truy van" class="btn-primary"/>
                <button name="action_preview" type="object"
                        string="Xem truoc (khong chay ORM)"
                        class="btn-secondary"/>
                <button special="cancel" string="Dong"/>
            </footer>
        </form>
    </field>
</record>

Tôi đặt invisible="not rationale" (cú pháp domain Odoo 17+) cho group phân tích. Chỉ khi parser đã chạy xong và đổ kết quả vào rationale, group này mới hiện. Trải nghiệm sạch hơn so với việc hiện group trống ngay từ đầu. Một cái bẫy đáng nhớ: trước Odoo 17 cú pháp là attrs="{'invisible': [('rationale', '=', False)]}". Cú pháp attrs đã bị bỏ trong Odoo 17, vì vậy Odoo 19 sẽ raise ValueError ngay lúc load view nếu lỡ giữ lại.

6. Security

Mỗi model phải có ít nhất một dòng trong security/ir.model.access.csv, ngay cả là TransientModel. Bỏ qua khiến Odoo crash AccessError lần đầu user mở wizard.

id,name,model_id:id,group_id:id,perm_read,perm_write,perm_create,perm_unlink
access_text_to_sql_query_log_user,access_text_to_sql_query_log_user,model_m_text_to_sql_query_log,base.group_user,1,1,1,0
access_text_to_sql_wizard_user,access_text_to_sql_wizard_user,model_m_text_to_sql_wizard,base.group_user,1,1,1,1

Tôi cho base.group_user (Internal User chuẩn) quyền read/write/create trên QueryLog nhưng KHÔNG cho unlink (perm_unlink=0). Lý do: audit trail là audit trail, người dùng không được tự xóa lịch sử của mình. Nếu sau này cần xóa hàng loạt cho retention policy, dùng một scheduled action chạy với sudo, không cấp quyền cho user. So với cách giản tiện 1,1,1,1 cho mọi cột, cách này tốn thêm 2 phút thiết kế nhưng tránh được vấn đề tuân thủ data retention về sau.

7. Workflow / business logic

Pipe hoàn chỉnh khi user bấm "Chay truy van":

def action_run(self):
    self.ensure_one()
    parsed = self._parse_or_raise()
    rendered_sql, params = parsed.render_sql()

    model = self.env[parsed.entity]
    records = model.search(parsed.domain)

    log = self.env['m.text_to_sql.query_log'].create({
        'input_text': self.input_text,
        'entity': parsed.entity,
        'domain_text': repr(parsed.domain),
        'rendered_sql': rendered_sql,
        'sql_params': json.dumps(params, ensure_ascii=False, default=str),
        'result_count': len(records),
    })

    return {
        'type': 'ir.actions.act_window',
        'name': _('Ket qua: %s') % parsed.entity,
        'res_model': parsed.entity,
        'view_mode': 'list,form',
        'domain': [('id', 'in', records.ids)],
        'target': 'current',
    }

Hai điểm so sánh đáng chú ý. Một, tôi gọi model.search(parsed.domain) chứ không phải self.env.cr.execute(rendered_sql, params). Path ORM chậm hơn raw SQL khoảng 50% trên các JOIN phức tạp (đo trên PostgreSQL 16 với 10k row sale.order). Đổi lại nó tôn trọng toàn bộ record-rule + ACL + active_test mà Odoo thêm vào ngầm. Bỏ qua những thứ đó để chạy raw SQL là mở cửa cho user đọc đơn hàng của công ty khác trong môi trường multi-company. Benchmark cụ thể trong lesson 4: query 100 dòng trả về sau 142ms p95, query 10k dòng trả về sau 780ms p95, đáp ứng yêu cầu < 800ms tôi đặt ra ban đầu.

Hai, tôi convert ValueError từ parser thành UserError. Mặc định Odoo sẽ trả về HTTP 500 + traceback cho mọi exception, còn UserError thì hiện như modal dialog có nội dung tiếng Việt friendly. Tôi đặt logic này trong helper _parse_or_raise() để mọi action (action_run, action_preview) đều share một entry point lỗi.

8. Test thủ công

Quy trình test thủ công sau khi clone repo + bỏ vào folder addon của Odoo:

git clone https://github.com/vytharion/text-to-sql-addon.git
ln -s "$(pwd)/text-to-sql-addon" /odoo/extra-addons/text_to_sql_addon

odoo-bin -i text_to_sql_addon --stop-after-init -d test_db --no-http

Bước 1: vào Settings, bật Developer Mode để hiện menu Apps đầy đủ.
Bước 2: vào Apps, Update Apps List, search "Text to SQL", bấm Install. Mất khoảng 8 giây.
Bước 3: từ menu trái, vào Tools, Text to SQL, Truy van tieng Viet. Wizard mở dạng modal.
Bước 4: ô nhập sẵn câu mẫu "don hang trong thang nay co tong tien lon hon 1 trieu". Bấm "Xem truoc (khong chay ORM)" để xem parser ra gì.
Bước 5: trong panel Phan tich, kiểm tra rationale có 3 dòng (entity, time range, amount). Kiểm tra rendered_sql hiện màu syntax SQL như SELECT * FROM sale_order WHERE date_order >= %s AND ....
Bước 6: bấm "Chay truy van" để chạy ORM thật. Nếu DB demo có sale.order, sẽ mở thẳng list view với filter đã apply.
Bước 7: vào Tools, Text to SQL, Lich su truy van để xem QueryLog row vừa tạo, mở chi tiết, vào tab SQL render để xác nhận params binding đúng.

Nếu muốn chạy unit test pure-Python cho parser (không cần Odoo runtime):

cd text-to-sql-addon
python3 -m unittest tests.test_vn_parser -v

12 test trong file test_vn_parser.py chạy xong dưới 200ms. Đó là một trong những lý do tôi tách parser thành module độc lập từ đầu, thay vì để nó nằm bên trong models/.

9. Repository

Full source at https://github.com/vytharion/text-to-sql-addon. Bốn lesson tạo addon từ trống đến hoàn chỉnh:

  • Lesson 0 (init scaffold) → 95ce40f — README + .gitignore
  • Lesson 1 (addon scaffold) → ed0922d — __manifest__.py + QueryLog model + security CSV
  • Lesson 2 (parser) → fd408e6 — vn_parser.py + 12 unit test pure-Python
  • Lesson 3 (wizard + view) → 847d4b9 — TransientModel + form view + menus
  • Lesson 4 (index + benchmark) → 8098e36 — 3 index cột + benchmark_orm_vs_sql helper

Để khám phá theo trình tự, clone repo rồi git checkout <sha> từng commit để xem code ở trạng thái cuối mỗi lesson. Tài liệu tham khảo bên ngoài: ORM reference của Odoo 19 tại https://www.odoo.com/documentation/19.0/developer/reference/backend/orm.html, PostgreSQL parameterized prepare statements tại https://www.postgresql.org/docs/16/sql-prepare.html, và upstream Odoo source tại https://github.com/odoo/odoo.

10. Kết luận + Bước tiếp

Bài này dựng một addon Odoo CE 19 đủ chức năng: parse tiếng Việt tự nhiên thành domain Odoo, gọi ORM search, ghi audit log, mở list view của entity tương ứng. Không file Python nào gọi self.env.cr.execute cho path runtime, raw SQL chỉ xuất hiện trong helper benchmark dev-only. Đó là kỷ luật quan trọng: hễ một developer bỏ cr.execute vào path user-facing, RLS của Odoo lập tức bị bypass và mọi công sức thiết lập security ở trên đổ sông.

Hướng mở rộng tiếp theo:

  1. Thêm tuan truoc, quy nay, nam ngoai vào _detect_time_window. Hiện chỉ support 4 khung thời gian, đủ 80% use case kế toán SME nhưng còn nhiều câu hỏi quý/năm trước đó mà parser bỏ qua.
  2. Hỗ trợ multiple amount clause: "tong tien lon hon 1 trieu va nho hon 10 trieu" hiện chỉ match clause đầu tiên. Cần loop qua tất cả phrase thay vì break sớm.
  3. Tích hợp với mail.thread để mỗi QueryLog trở thành record có audit chatter, cho phép chú thích thêm câu hỏi sau khi chạy.
  4. Thay parser regex bằng một mô hình ngôn ngữ nhỏ chạy local (ví dụ phoBERT fine-tuned) khi câu hỏi vượt khả năng template match. Đây là việc dài hơi, không phù hợp cho addon đơn nhất, nhưng đáng để nghiên cứu nếu volume câu hỏi tăng.

Mã nguồn open source LGPL-3. Clone về, sửa, gửi PR. Câu hỏi tiếng Việt ngày càng đa dạng, mỗi PR thêm phrase mới là một bước nữa giúp kế toán Việt Nam thoát khỏi việc nhớ domain syntax của Odoo.

Repository

https://github.com/vytharion/text-to-sql-addon